Skip to content

Instantly share code, notes, and snippets.

@cameronsjo

cameronsjo/THEME-REFERENCE.md

Last active August 31, 2026 17:16
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save cameronsjo/34a6fb8ade2b44c8380e1a2adebbac2b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save cameronsjo/34a6fb8ade2b44c8380e1a2adebbac2b to your computer and use it in GitHub Desktop.
Download ZIP
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.
Raw
THEME-REFERENCE.md

Claude Code Theme Reference

A complete reference for the ~/.claude/themes/*.json schema, including all 72 reachable tokens (reconciled 2026-08-30 against Claude Code 2.1.251). 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
autoAcceptShimmer Internal Shimmer paired with autoAccept
skill Internal Skill-invocation accent; shares its value with autoAccept
effortUltra Internal Ultra effort / thinking-level indicator
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
composerSidebarBackground Internal Background fill for the fullscreen composer sidebar
messageActionsBackground Internal Background fill behind per-message action affordances. Removed from the preset since v2.1.140 — overrides are now ignored.
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

What the theme cannot do

Custom themes only control the prebuilt UI tokens above. Code-block coloring is a separate subsystem and is not theme-controllable.

Code blocks are syntax-highlighted by highlight.js, which Claude Code maps to hardcoded ANSI scopes in the binary (ae object), not to theme tokens. The mapping is fixed:

keyword → blue    (ANSI)
literal → blue
class   → blue
name    → blue
string  → red
number  → green
comment → green

So there is no code, codeBlock, inlineCode, or syntax* key in the preset, and no overrides entry can recolor code text. Why this matters: if your theme "code blue" looks wrong (e.g. washy), the fix lives in your terminal's ANSI palette, not the theme. The theme's text/muted etc. trust the terminal's ANSI fg for default text, but hljs keywords resolve straight to ANSI blue (34) through the terminal palette.

In short: accent, borders, status, diffs, backgrounds → theme tokens. Code syntax highlighting → fixed hljs ANSI map (change your terminal palette or a custom hljs emitter).

The hljs scope→ANSI map (from 2.1.251)

The full scope map is baked into the binary's Var ae={...} with chalk-style ANSI: keyword: ae.blue, built_in: ae.cyan, type: ae.cyan.dim, literal: ae.blue, number: ae.green, string: ae.red, comment: ae.green, doctag: ae.green, meta: ae.grey, tag: ae.grey, name: ae.blue, attr: ae.cyan. These resolve to ANSI index numbers (34 blue, 36 cyan, 32 green, 31 red, 37 grey), so the actual hue is whatever your terminal assigns those index. If you want code text to be #c4808a-style rose, restyle at the terminal.

Methodology

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

strings -n 4 ~/.local/share/claude/versions/<version> > /tmp/cc-strings.txt
python3 - <<'PY'
import re
raw = open('/tmp/cc-strings.txt', encoding='utf-8', errors='replace').read()
m = re.search(r'var v=\{(.*?)\},Y=\{', raw)
keys = re.findall(r'([A-Za-z_][A-Za-z0-9_]*):"(?:rgb|ansi)', m.group(1))
print(len(keys))
PY

That grabs the first (light) preset object — six preset variables (v, Y, L, G, F, B) all share the same key set; the 72 keys define the complete tunable surface. Any future token Anthropic adds appears in those preset literals first; rerun the count against a newer binary and re-check the token list. The preset objects also expose the non-theme hljs ANSI map (Var ae={...} / Var l=new Map(...)), the thing that colors code blocks — see "What the theme cannot do".

See also

Raw
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.251 binary (72 preset keys); 61 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": "Documented. 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": "Documented. Shimmer variant of `permission` for animated gradients."
},
"remember": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Memory and `CLAUDE.md` indicators."
},
"suggestion": {
"$ref": "#/$defs/colorValue",
"description": "Documented. 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": "Documented. 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."
},
"autoAcceptShimmer": {
"$ref": "#/$defs/colorValue",
"description": "Internal. Shimmer variant of `autoAccept` for animated gradients."
},
"skill": {
"$ref": "#/$defs/colorValue",
"description": "Internal. Skill-invocation accent; shares its value with `autoAccept` in the default preset."
},
"effortUltra": {
"$ref": "#/$defs/colorValue",
"description": "Internal. Ultra effort / thinking-level indicator."
},
"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": "Documented. 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": "Documented. Hover-state variant of `userMessageBackground`."
},
"composerSidebarBackground": {
"$ref": "#/$defs/colorValue",
"description": "Internal. Background fill for the fullscreen composer sidebar."
},
"messageActionsBackground": {
"$ref": "#/$defs/colorValue",
"description": "Internal. Background fill behind per-message action affordances. Absent from the preset since v2.1.140."
},
"selectionBg": {
"$ref": "#/$defs/colorValue",
"description": "Documented (fullscreen mode only). Background of text selected with the mouse."
},
"bashMessageBackgroundColor": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Background fill for shell-command (`!`) messages in fullscreen mode."
},
"memoryBackgroundColor": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Background fill for memory / `CLAUDE.md` annotations in fullscreen mode."
},
"rate_limit_fill": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Filled portion of the rate-limit usage bar."
},
"rate_limit_empty": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Empty portion of the rate-limit usage bar."
},
"briefLabelYou": {
"$ref": "#/$defs/colorValue",
"description": "Documented. \"You\" label color in brief / compact transcript mode."
},
"briefLabelClaude": {
"$ref": "#/$defs/colorValue",
"description": "Documented. \"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": "Documented. Red stop in the rainbow palette (animated celebration sequences)."
},
"rainbow_orange": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Orange stop in the rainbow palette."
},
"rainbow_yellow": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Yellow stop in the rainbow palette."
},
"rainbow_green": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Green stop in the rainbow palette."
},
"rainbow_blue": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Blue stop in the rainbow palette."
},
"rainbow_indigo": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Indigo stop in the rainbow palette."
},
"rainbow_violet": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Violet stop in the rainbow palette."
},
"rainbow_red_shimmer": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Shimmer paired with `rainbow_red`."
},
"rainbow_orange_shimmer": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Shimmer paired with `rainbow_orange`."
},
"rainbow_yellow_shimmer": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Shimmer paired with `rainbow_yellow`."
},
"rainbow_green_shimmer": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Shimmer paired with `rainbow_green`."
},
"rainbow_blue_shimmer": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Shimmer paired with `rainbow_blue`."
},
"rainbow_indigo_shimmer": {
"$ref": "#/$defs/colorValue",
"description": "Documented. Shimmer paired with `rainbow_indigo`."
},
"rainbow_violet_shimmer": {
"$ref": "#/$defs/colorValue",
"description": "Documented. 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`."
}
]
}
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment