JSON Schema and reference doc covering all 69 color tokens for ~/.claude/themes/*.json (Claude Code v2.1.x). Token list reverse-engineered from the binary; ~35 are officially documented and the rest are internal but reachable. Strict JSON Schema for editor validation.

THEME-REFERENCE.md

Claude Code Theme Reference

A complete reference for the ~/.claude/themes/*.json schema, including all 69 reachable tokens. Pairs with theme.schema.json for editor validation and autocomplete.

Custom themes require Claude Code v2.1.118 or later.

Quick start

// ~/.claude/themes/my-theme.json
{
  "$schema": "./theme.schema.json",
  "name": "My Theme",
  "base": "dark",
  "overrides": {
    "claude": "#a89278",
    "error": "#e8836f",
    "success": "#b7bd73"
  }
}

Selecting the theme via /theme stores custom:<filename-slug> as the preference. Claude Code watches the directory and reloads on file change.

Top-level fields

Field	Type	Required	Description
$schema	string	No	Editor hint for autocomplete/validation. Ignored by Claude Code.
name	string	No	Display label in /theme. Defaults to filename slug.
base	enum	No	Built-in preset to inherit from. Defaults to dark.
overrides	object	No	Sparse map of token → color. Tokens not listed fall through to base.

Base presets

base value	Notes
dark	Default; standard dark theme.
light	Standard light theme.
dark-daltonized	Dark variant tuned for color-vision-deficiency safety.
light-daltonized	Light daltonized variant.
dark-ansi	Uses 16-color ANSI palette only — best for terminals with custom palettes.
light-ansi	ANSI light variant.

Color value formats

Form	Pattern	Example
Hex RGB	#rrggbb	#a89278
Short hex	#rgb	#a87
Functional RGB	rgb(r,g,b)	rgb(168, 146, 120)
256-color	ansi256(n) (0–255)	ansi256(180)
Named ANSI	ansi:<name>	ansi:cyanBright

The 16 valid ANSI names: red, green, blue, yellow, magenta, cyan, white, black, plus a Bright suffix on each (redBright, greenBright, …).

Failure mode

Per the official docs: "Unknown tokens and invalid color values are ignored, so a typo cannot break rendering." Strict validation in theme.schema.json catches typos in your editor — runtime is forgiving either way.

Token catalog

Badges:

• Documented — listed in the official color token reference
• Internal — present in the binary's preset object, reachable via overrides, but not in the public docs (descriptions inferred from naming and surrounding code)

Brand and accent

Token	Status	Controls
claude	Documented	Primary brand accent — spinner, assistant label
claudeShimmer	Documented	Lighter color paired with claude in animated gradients
claudeBlue_FOR_SYSTEM_SPINNER	Internal	Blue brand variant for the system spinner
claudeBlueShimmer_FOR_SYSTEM_SPINNER	Internal	Shimmer paired with claudeBlue_FOR_SYSTEM_SPINNER
professionalBlue	Internal	Anthropic-blue marketing accent (login, billing)
chromeYellow	Internal	Yellow marketing accent

Foreground text

Token	Status	Controls
text	Documented	Default foreground text
inverseText	Documented	Text on top of colored backgrounds (badges)
inactive	Documented	Hints, timestamps, disabled items
inactiveShimmer	Internal	Shimmer paired with inactive
subtle	Documented	Faint borders and de-emphasized text
suggestion	Internal	Suggestion-tier UI accents (autocomplete hints)
remember	Documented	Memory and CLAUDE.md indicators
background	Internal	Generic surface background fill

Status

Token	Status	Controls
success	Documented	Success messages and passing checks
error	Documented	Errors and failures
warning	Documented	Warnings, cautions, auto-mode border
warningShimmer	Documented	Shimmer paired with warning
merged	Documented	Merged pull request status

Input box and mode indicators

Token	Status	Controls
promptBorder	Documented	Input box border (default mode)
promptBorderShimmer	Internal	Shimmer paired with promptBorder
permission	Documented	Permission prompts and pickers
permissionShimmer	Internal	Shimmer paired with permission
planMode	Documented	Plan mode accent and border
autoAccept	Documented	Accept-edits mode accent and border
bashBorder	Documented	Input border when entering ! shell command
ide	Documented	IDE connection indicator
fastMode	Documented	Fast mode indicator
fastModeShimmer	Internal	Shimmer paired with fastMode

Diff rendering

Token	Status	Controls
diffAdded	Documented	Background of added lines
diffRemoved	Documented	Background of removed lines
diffAddedDimmed	Documented	Unchanged context near added lines
diffRemovedDimmed	Documented	Unchanged context near removed lines
diffAddedWord	Documented	Word-level highlight in added lines
diffRemovedWord	Documented	Word-level highlight in removed lines

Fullscreen mode (background fills)

These apply only when /tui fullscreen rendering is active.

Token	Status	Controls
userMessageBackground	Documented	Background behind user messages
userMessageBackgroundHover	Internal	Hover variant of userMessageBackground
messageActionsBackground	Internal	Per-message action affordance backgrounds
bashMessageBackgroundColor	Internal	Background for shell-command messages
memoryBackgroundColor	Internal	Background for memory / CLAUDE.md annotations
selectionBg	Documented	Mouse-selection background

Subagent palette

Subagents declared with color: <name> in their YAML frontmatter draw using the matching token. Override these to recolor your agent transcripts.

Token	Status
red_FOR_SUBAGENTS_ONLY	Documented
blue_FOR_SUBAGENTS_ONLY	Documented
green_FOR_SUBAGENTS_ONLY	Documented
yellow_FOR_SUBAGENTS_ONLY	Documented
purple_FOR_SUBAGENTS_ONLY	Documented
orange_FOR_SUBAGENTS_ONLY	Documented
pink_FOR_SUBAGENTS_ONLY	Documented
cyan_FOR_SUBAGENTS_ONLY	Documented

Rate-limit indicator

Token	Status	Controls
rate_limit_fill	Internal	Filled portion of the usage bar
rate_limit_empty	Internal	Empty portion of the usage bar

Brief mode

Token	Status	Controls
briefLabelYou	Internal	"You" label in compact transcript mode
briefLabelClaude	Internal	"Claude" label in compact transcript mode

Mascot easter egg

Token	Status	Controls
clawd_body	Internal	Body color for the Clawd mascot art
clawd_background	Internal	Background behind the Clawd mascot art

Rainbow palette (animated celebration sequences)

Each color has a *_shimmer partner for gradient animation.

Pair	Status
rainbow_red / rainbow_red_shimmer	Internal
rainbow_orange / rainbow_orange_shimmer	Internal
rainbow_yellow / rainbow_yellow_shimmer	Internal
rainbow_green / rainbow_green_shimmer	Internal
rainbow_blue / rainbow_blue_shimmer	Internal
rainbow_indigo / rainbow_indigo_shimmer	Internal
rainbow_violet / rainbow_violet_shimmer	Internal

Methodology

The 35 documented tokens come from the official docs at https://code.claude.com/docs/en/terminal-config#color-token-reference. The remaining 34 internal tokens were extracted from the canonical preset object inside the Claude Code 2.1.126 binary at ~/.local/share/claude/versions/<version>:

strings -n 4 ~/.local/share/claude/versions/<version> > /tmp/cc-strings.txt
awk '/claudeShimmer/ { p=index($0,"YD4="); print substr($0,p,8000); exit }' /tmp/cc-strings.txt

That dumps the dark preset object — six preset variables (YD4, wD4, DD4, jD4, JD4, MD4) all share the same key set; the 69 keys define the complete tunable surface. Any future token added by Anthropic will appear in those preset literals first; rerun the awk extraction against a newer binary to refresh this catalog.

See also

• theme.schema.json — JSON Schema for editor validation
• artificer.json — example custom theme
• Official theme docs
• Plugins reference: themes — for shipping themes via plugins

theme.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Claude Code Theme",
  "description": "Schema for Claude Code custom themes (~/.claude/themes/*.json). Requires Claude Code v2.1.118 or later. Token list reverse-engineered from the 2.1.126 binary; ~35 tokens are officially documented at https://code.claude.com/docs/en/terminal-config#color-token-reference and the rest are internal but reachable via overrides. Unknown tokens and invalid color values are silently ignored at runtime, so a typo cannot break rendering — but this schema flags them so you catch typos in your editor.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Reference to this schema for editor autocomplete and validation."
    },
    "name": {
      "type": "string",
      "description": "Display label shown in /theme. Defaults to the filename slug."
    },
    "base": {
      "type": "string",
      "default": "dark",
      "description": "Built-in preset the theme starts from. Tokens not listed in `overrides` fall through to the base preset. Defaults to `dark`.",
      "enum": [
        "dark",
        "light",
        "dark-daltonized",
        "light-daltonized",
        "dark-ansi",
        "light-ansi"
      ]
    },
    "overrides": {
      "type": "object",
      "description": "Map of color token names to color values. Tokens not listed fall through to the base preset.",
      "additionalProperties": false,
      "properties": {
        "claude": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Primary brand accent, used for the spinner and assistant label."
        },
        "claudeShimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Lighter color paired with `claude` in the spinner's animated gradient."
        },
        "claudeBlue_FOR_SYSTEM_SPINNER": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Blue variant of the brand accent used by the system spinner; pairs with `claudeBlueShimmer_FOR_SYSTEM_SPINNER`."
        },
        "claudeBlueShimmer_FOR_SYSTEM_SPINNER": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Lighter shimmer paired with `claudeBlue_FOR_SYSTEM_SPINNER`."
        },
        "text": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Default foreground text."
        },
        "inverseText": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Text drawn on top of a colored background, such as status badges."
        },
        "inactive": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Secondary text such as hints, timestamps, and disabled items."
        },
        "inactiveShimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer variant of `inactive` for animated gradients."
        },
        "subtle": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Faint borders and de-emphasized secondary text."
        },
        "permission": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Dialog borders, including permission prompts and pickers."
        },
        "permissionShimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer variant of `permission` for animated gradients."
        },
        "remember": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Memory and `CLAUDE.md` indicators."
        },
        "suggestion": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Suggestion-tier UI accents (autocomplete prompts, hint banners)."
        },
        "background": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. General background fill for surfaces that opt into a color (rare)."
        },
        "success": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Success messages and passing checks."
        },
        "error": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Error messages and failures."
        },
        "warning": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Warnings, caution messages, and the auto mode border."
        },
        "warningShimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Lighter color paired with `warning` in animated gradients."
        },
        "merged": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Merged pull request status."
        },
        "promptBorder": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Input box border in the default permission mode."
        },
        "promptBorderShimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer variant of `promptBorder` for animated gradients."
        },
        "planMode": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Plan mode accent and border."
        },
        "autoAccept": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Accept-edits mode accent and border."
        },
        "bashBorder": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Input box border when entering a `!` shell command."
        },
        "ide": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. IDE connection indicator."
        },
        "fastMode": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Fast mode indicator."
        },
        "fastModeShimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer variant of `fastMode` for animated gradients."
        },
        "diffAdded": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Background of added lines."
        },
        "diffRemoved": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Background of removed lines."
        },
        "diffAddedDimmed": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Background of unchanged context near added lines."
        },
        "diffRemovedDimmed": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Background of unchanged context near removed lines."
        },
        "diffAddedWord": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Word-level highlight within an added line."
        },
        "diffRemovedWord": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Word-level highlight within a removed line."
        },
        "userMessageBackground": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented (fullscreen mode only). Background behind your messages in the transcript."
        },
        "userMessageBackgroundHover": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Hover-state variant of `userMessageBackground`."
        },
        "messageActionsBackground": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Background fill behind per-message action affordances."
        },
        "selectionBg": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented (fullscreen mode only). Background of text selected with the mouse."
        },
        "bashMessageBackgroundColor": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Background fill for shell-command (`!`) messages in fullscreen mode."
        },
        "memoryBackgroundColor": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Background fill for memory / `CLAUDE.md` annotations in fullscreen mode."
        },
        "rate_limit_fill": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Filled portion of the rate-limit usage bar."
        },
        "rate_limit_empty": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Empty portion of the rate-limit usage bar."
        },
        "briefLabelYou": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. \"You\" label color in brief / compact transcript mode."
        },
        "briefLabelClaude": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. \"Claude\" label color in brief / compact transcript mode."
        },
        "professionalBlue": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Anthropic-blue brand accent used in marketing surfaces (login screens, billing UI)."
        },
        "chromeYellow": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Yellow accent used in marketing surfaces."
        },
        "clawd_body": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Body color for the Clawd mascot easter-egg art."
        },
        "clawd_background": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Background color behind the Clawd mascot easter-egg art."
        },
        "rainbow_red": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Red stop in the rainbow palette (animated celebration sequences)."
        },
        "rainbow_orange": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Orange stop in the rainbow palette."
        },
        "rainbow_yellow": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Yellow stop in the rainbow palette."
        },
        "rainbow_green": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Green stop in the rainbow palette."
        },
        "rainbow_blue": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Blue stop in the rainbow palette."
        },
        "rainbow_indigo": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Indigo stop in the rainbow palette."
        },
        "rainbow_violet": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Violet stop in the rainbow palette."
        },
        "rainbow_red_shimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer paired with `rainbow_red`."
        },
        "rainbow_orange_shimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer paired with `rainbow_orange`."
        },
        "rainbow_yellow_shimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer paired with `rainbow_yellow`."
        },
        "rainbow_green_shimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer paired with `rainbow_green`."
        },
        "rainbow_blue_shimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer paired with `rainbow_blue`."
        },
        "rainbow_indigo_shimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer paired with `rainbow_indigo`."
        },
        "rainbow_violet_shimmer": {
          "$ref": "#/$defs/colorValue",
          "description": "Internal. Shimmer paired with `rainbow_violet`."
        },
        "red_FOR_SUBAGENTS_ONLY": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Color drawn for subagents declared with `color: red`. See https://code.claude.com/docs/en/sub-agents."
        },
        "blue_FOR_SUBAGENTS_ONLY": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Color drawn for subagents declared with `color: blue`."
        },
        "green_FOR_SUBAGENTS_ONLY": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Color drawn for subagents declared with `color: green`."
        },
        "yellow_FOR_SUBAGENTS_ONLY": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Color drawn for subagents declared with `color: yellow`."
        },
        "purple_FOR_SUBAGENTS_ONLY": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Color drawn for subagents declared with `color: purple`."
        },
        "orange_FOR_SUBAGENTS_ONLY": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Color drawn for subagents declared with `color: orange`."
        },
        "pink_FOR_SUBAGENTS_ONLY": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Color drawn for subagents declared with `color: pink`."
        },
        "cyan_FOR_SUBAGENTS_ONLY": {
          "$ref": "#/$defs/colorValue",
          "description": "Documented. Color drawn for subagents declared with `color: cyan`."
        }
      }
    }
  },
  "$defs": {
    "colorValue": {
      "type": "string",
      "description": "A color in one of: `#rrggbb`, `#rgb`, `rgb(r,g,b)`, `ansi256(n)` (n = 0–255), or `ansi:<name>` where <name> is one of the 16 standard ANSI names (red, green, blue, yellow, magenta, cyan, white, black, plus their `Bright` variants).",
      "oneOf": [
        {
          "pattern": "^#[0-9a-fA-F]{6}$",
          "description": "Hex RGB, e.g. `#a89278`."
        },
        {
          "pattern": "^#[0-9a-fA-F]{3}$",
          "description": "Short hex RGB, e.g. `#a87`."
        },
        {
          "pattern": "^rgb\\(\\s*(0|[1-9]\\d?|1\\d\\d|2[0-4]\\d|25[0-5])\\s*,\\s*(0|[1-9]\\d?|1\\d\\d|2[0-4]\\d|25[0-5])\\s*,\\s*(0|[1-9]\\d?|1\\d\\d|2[0-4]\\d|25[0-5])\\s*\\)$",
          "description": "Functional RGB, e.g. `rgb(168, 146, 120)`."
        },
        {
          "pattern": "^ansi256\\((0|[1-9]\\d?|1\\d\\d|2[0-4]\\d|25[0-5])\\)$",
          "description": "256-color ANSI palette index, e.g. `ansi256(180)`."
        },
        {
          "pattern": "^ansi:(red|green|blue|yellow|magenta|cyan|white|black)(Bright)?$",
          "description": "Named ANSI color, e.g. `ansi:cyanBright`."
        }
      ]
    }
  }
}