Auto-Switching Claude Code Theme with macOS Appearance

Properties2

Type	Practice
Note created	May 18, 2026

I wanted Claude Code to follow macOS light/dark appearance live, the way cmux already does for its terminal themes. Claude Code ships an auto theme but it only picks between built-in presets, not custom ones — so we built a custom Catppuccin theme and then hit the real obstacle: Claude Code’s theme file watcher reloads theme contents in ~/.claude/themes/ live, but it caches the active selection per session, so changing settings.json.theme mid-session is a no-op until restart.

• Define a single active theme file (e.g. ~/.claude/themes/catppuccin.json) and set settings.json.theme to custom:catppuccin once — never change it again.
• Keep both palettes (Mocha + Latte) as separate source files in a repo; the sync script just copies the matching one over the active file.
• Use a launchd LaunchAgent with WatchPaths on ~/Library/Preferences/.GlobalPreferences.plist (where macOS persists the appearance setting) — no Swift daemon needed, no polling.
• Expect a ~5–10s debounce on rapid successive appearance toggles (launchd coalesces WatchPaths events). Real user toggles are instant.
• Atomic writes (cp tmp && mv tmp dst) trigger the file watcher reliably; touch may not, since some watchers only fire on content writes.
• In any already-open Claude Code session, run /theme once and re-pick the theme so the session caches the new active slug.
• Theme token reference is at code.claude.com/docs/en/terminal-config#match-the-color-theme. Useful ones beyond claude (brand accent): suggestion (selected picker items), permission (picker/dialog borders), planMode, autoAccept.

Full implementation lives at ~/Projects/Personal/claude-code-catppuccin.