# rafsanmuhammed/claude-code-themes architecture

> Architecture diagram of the GitHub repository rafsanmuhammed/claude-code-themes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rafsanmuhammed/claude-code-themes
- Repository: https://github.com/rafsanmuhammed/claude-code-themes

## Overview

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.

Main entry points: [`claude-theme`](https://github.com/rafsanmuhammed/claude-code-themes/tree/main/claude-theme) (claude-theme), [`install.sh`](https://github.com/rafsanmuhammed/claude-code-themes/blob/main/install.sh) (install.sh), [`README.md`](https://github.com/rafsanmuhammed/claude-code-themes/blob/main/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_distribution["Distribution"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_install_sh["install.sh<br/>installer<br/>[install.sh]"]
end

subgraph group_cli["Theme CLI"]
  node_claude_theme_bin["claude-theme<br/>cli"]
  node_theme_registry["Theme registry<br/>catalog"]
  node_apply_cmd["apply<br/>command"]
  node_list_cmd["list<br/>command"]
  node_preview_cmd["preview<br/>command"]
  node_current_cmd["current<br/>command"]
  node_reset_cmd["reset<br/>command"]
end

subgraph group_themes["Theme Assets"]
  node_theme_bundle[("Theme bundle")]
end

subgraph group_state["User State"]
  node_claude_settings["Claude settings<br/>json config"]
  node_theme_cache[("Theme cache<br/>copied assets")]
  node_local_bin[("Local bin<br/>install target")]
end

subgraph group_external["External Tools"]
  node_claude_code["Claude Code<br/>terminal app"]
  node_shell_env["Shell env<br/>environment"]
  node_oh_my_posh["Oh My Posh<br/>optional statusline"]
end

node_readme -->|"documents"| node_install_sh
node_readme -->|"documents"| node_claude_theme_bin
node_install_sh -->|"installs"| node_local_bin
node_install_sh -->|"copies"| node_theme_cache
node_claude_theme_bin -->|"loads"| node_theme_registry
node_theme_registry -->|"indexes"| node_theme_bundle
node_claude_theme_bin -->|"dispatches"| node_apply_cmd
node_claude_theme_bin -->|"dispatches"| node_list_cmd
node_claude_theme_bin -->|"dispatches"| node_preview_cmd
node_claude_theme_bin -->|"dispatches"| node_current_cmd
node_claude_theme_bin -->|"dispatches"| node_reset_cmd
node_apply_cmd -->|"selects"| node_theme_bundle
node_apply_cmd -->|"writes"| node_claude_settings
node_apply_cmd -->|"exports"| node_shell_env
node_apply_cmd -.->|"points to"| node_oh_my_posh
node_claude_settings -->|"configures"| node_claude_code
node_shell_env -->|"influences"| node_claude_code
node_oh_my_posh -.->|"augments"| node_claude_code
node_reset_cmd -->|"clears"| node_claude_settings
node_theme_bundle -->|"installs"| node_theme_cache

click node_readme "https://github.com/rafsanmuhammed/claude-code-themes/blob/main/README.md"
click node_install_sh "https://github.com/rafsanmuhammed/claude-code-themes/blob/main/install.sh"
click node_claude_theme_bin "https://github.com/rafsanmuhammed/claude-code-themes/tree/main/claude-theme"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_install_sh toneBlue
class node_claude_theme_bin,node_theme_registry,node_apply_cmd,node_list_cmd,node_preview_cmd,node_current_cmd,node_reset_cmd toneAmber
class node_theme_bundle toneMint
class node_claude_settings,node_theme_cache,node_local_bin toneRose
class node_claude_code,node_shell_env,node_oh_my_posh toneIndigo
```

## Components

### Distribution

Repo entrypoints and documentation

- [README](https://github.com/rafsanmuhammed/claude-code-themes/blob/main/README.md): docs · Main product documentation: themes, commands, install flow, and limitations · `README.md`
- [install.sh](https://github.com/rafsanmuhammed/claude-code-themes/blob/main/install.sh): installer · Bootstrap installer for curl|bash setup · `install.sh`

### Theme CLI

Installer and command-line control plane

- [claude-theme](https://github.com/rafsanmuhammed/claude-code-themes/tree/main/claude-theme): cli · User-facing command for theme discovery and lifecycle operations · `claude-theme`
- **Theme registry**: catalog · Registered list of available themes and metadata
- **apply**: command · Selects a theme and materializes it locally
- **list**: command · Enumerates available themes
- **preview**: command · Shows a theme before activation
- **current**: command · Reports the active theme
- **reset**: command · Removes theme customizations and returns to defaults

### Theme Assets

Packaged theme bundles and registry

- **Theme bundle**: package · A theme package containing Claude settings, shell env, and optional Oh My Posh config

### User State

Files written into the home directory

- **Claude settings**: json config · Theme-specific Claude Code settings written to the user profile
- **Theme cache**: copied assets · Installed theme files stored in the user home directory
- **Local bin**: install target · Installed claude-theme executable location

### External Tools

Claude Code and optional shell/statusline integration

- **Claude Code**: terminal app · Target application whose settings and prompt color are configured by the repo
- **Shell env**: environment · Exports theme variables such as CLAUDE_CODE_THEME and COLORTERM=truecolor
- **Oh My Posh**: optional statusline · Optional statusline renderer pointed at the matching theme file

## Connections

- README → install.sh: documents · Explains the bootstrap install path
- README → claude-theme: documents · Describes the CLI commands and theme catalog
- install.sh → Local bin: installs · Places the executable in the user's bin directory
- install.sh → Theme cache: copies · Installs bundled theme assets into the home directory
- claude-theme → Theme registry: loads · Uses the theme registry to discover available bundles
- Theme registry → Theme bundle: indexes · Maps names like nord and dracula to packaged assets
- claude-theme → apply: dispatches · Routes apply requests to the theme application flow
- claude-theme → list: dispatches · Routes list requests to theme discovery
- claude-theme → preview: dispatches · Routes preview requests to a read-only theme view
- claude-theme → current: dispatches · Reports the active theme
- claude-theme → reset: dispatches · Resets theme state
- apply → Theme bundle: selects · Chooses one theme package to materialize
- apply → Claude settings: writes · Updates Claude Code configuration for the selected theme
- apply → Shell env: exports · Sets theme-related shell variables
- apply → Oh My Posh: points to · Optionally configures a matching statusline theme
- Claude settings → Claude Code: configures · Feeds the terminal app's active settings
- Shell env → Claude Code: influences · Supplies terminal color and theme environment
- Oh My Posh → Claude Code: augments · Adds optional statusline integration alongside Claude Code
- reset → Claude settings: clears · Removes applied theme configuration
- Theme bundle → Theme cache: installs · Bundles are copied into the local theme store