rafsanmuhammed/claude-code-themes

1. What this repo is

- This is a small, shell-based distribution for styling Claude Code in the terminal.

- It does not run a server or background service; it ships theme assets plus an installer/CLI that writes into the user’s home directory.

2. Top-level structure

- The repository is centered around three visible pieces: install.sh, the claude-theme package/directory, and the README.

- The README is the main product surface: it documents the theme catalog, commands, install flow, and known limitations.

3. Primary entrypoint

- install.sh is the bootstrap path for end users.

- The repo is designed to be installed with curl ... | bash, which means the installer is the main orchestration layer for copying the CLI and theme assets onto the local machine.

4. Theme management layer

- The claude-theme component is the user-facing command-line tool.

- Its responsibilities are theme discovery and lifecycle operations such as apply, list, preview, current, and reset.

- Architecturally, this is the control plane for selecting a theme and materializing it into local Claude Code config.

5. Theme asset bundle

- Each theme is packaged as a unit containing three configuration artifacts:

- Claude Code settings JSON

- shell environment script

- optional Oh My Posh statusline config

- The repo’s themes are named bundles like nord, catppuccin-mocha, dracula, tokyo-night, and gruvbox.

6. Where state is written

- The CLI and installer do not store runtime state inside the repo; they write into the user environment:

- ~/.claude/settings.json for Claude Code configuration

- ~/.claude-themes/themes/ for copied theme assets

- ~/.local/bin/ for the installed claude-theme executable

- This makes the repo a source distribution, while the user’s home directory becomes the active configuration store.

7. Configuration flow when a theme is applied

- A user chooses a theme with claude-theme apply ....

- That selection updates Claude Code settings, sets environment variables such as CLAUDE_CODE_THEME and COLORTERM=truecolor, and can optionally point Oh My Posh at the matching theme file.

- After applying, the user still performs a separate Claude Code action to set the prompt bar color with /color ....

8. Optional statusline integration

- Oh My Posh is an optional external dependency, not required for basic theming.

- When present, it adds a themed statusline that can display Claude model, token usage, and session cost.

- This is a separate boundary from Claude Code itself: the repo only supplies the config pointing Oh My Posh at the right theme file.

9. System boundaries and limitations

- The repo can affect Claude Code’s settings, prompt color, shell environment, and statusline design.

- It cannot override hardcoded UI colors inside Claude Code’s TUI, such as diff block backgrounds or selection highlights.

- That limitation is important for the architecture diagram: the repo is a configuration layer, not a UI renderer.

10. Contribution model

- New themes are added by creating a new theme folder with the three config files and registering it in the CLI’s theme list.

- So the extensibility boundary is simple: add assets, update the theme registry, and ship the package.