Theme and Visual Styling System

§1 The Big Picture

Terminal styling in Claude Code is not a thin wrapper around chalk. It is a deliberately layered system that must survive at least three hostile environments: VS Code's embedded terminal (which lies about its color support), tmux (which silently drops truecolor backgrounds), and Apple Terminal (which can't handle 24-bit SGR sequences at all). Each layer has a single job, and they compose cleanly.

§2 The Theme Type System

The core data structure lives in utils/theme.ts. The Theme type is a flat record of ~70 named string slots. Every slot holds a raw color value — no nesting, no tokens-inside-tokens. This flatness is intentional: any component anywhere can look up a color in O(1) with zero risk of infinite resolution loops.

export type Theme = {
  // Brand identity
  claude: string          // rgb(215,119,87) — "Claude orange"
  claudeShimmer: string  // Lighter version for shimmer animation

  // UI surface roles
  promptBorder: string
  userMessageBackground: string
  selectionBg: string    // Alt-screen text selection highlight

  // Semantic roles
  success: string
  error: string
  warning: string

  // Diff colors (4 variants per operation)
  diffAdded: string
  diffAddedDimmed: string
  diffAddedWord: string

  // Agent colors — named to discourage general use
  red_FOR_SUBAGENTS_ONLY: string
  blue_FOR_SUBAGENTS_ONLY: string
  // ... 6 more

  // Rainbow colors for ultrathink keyword highlighting
  rainbow_red: string
  rainbow_red_shimmer: string
  // ... 12 more rainbow slots
}

The naming conventions tell a story. _FOR_SUBAGENTS_ONLY suffixes act as lint-time guardrails — you can visually grep for misuse. The Shimmer suffix signals that a color exists purely as the lighter step in a pulse animation, never for static text. The _FOR_SYSTEM_SPINNER suffix isolates the blue used by Claude's own spinner from user-visible permission prompts.

The Six Themes

There are exactly six concrete theme objects, mapped by the ThemeName union:

export const THEME_NAMES = [
  'dark',
  'light',
  'light-daltonized',
  'dark-daltonized',
  'light-ansi',
  'dark-ansi',
] as const

export const THEME_SETTINGS = ['auto', ...THEME_NAMES] as const
// ThemeSetting is stored in config; ThemeName is resolved at runtime

The auto setting is only valid in config storage — it is resolved to either dark or light by following the system's dark/light mode at runtime, then replaced by a concrete ThemeName before any component touches a color token.

§3 Dark vs. Light vs. Daltonized — What Actually Changes

The three families (dark, light, daltonized) differ in more than just brightness. The daltonized variants systematically replace green-red distinctions with blue-red ones, because deuteranopia (the most common form of color blindness) affects the green channel. Here's how a few key tokens change across the three dark variants:

Notice that success in dark-daltonized is bright blue, not green. Someone with deuteranopia cannot rely on green to mean "good" — so the daltonized theme substitutes blue, which is on a completely different channel. The diffAdded token shifts from dark green to dark blue for the same reason.

§4 colorize.ts — The Terminal Environment Problem

This is where the engineering gets interesting. The file opens with two long block comments explaining two separate terminal environment bugs, and then fixes both at module load time — before any color is ever rendered.

Problem 1: VS Code Lies About Its Color Support

function boostChalkLevelForXtermJs(): boolean {
  // xterm.js has supported truecolor since 2017, but code-server/Coder
  // containers often don't set COLORTERM=truecolor. chalk's supports-color
  // doesn't recognize TERM_PROGRAM=vscode (it only knows iTerm.app/
  // Apple_Terminal), so it falls through to the -256color regex → level 2.
  // At level 2, chalk.rgb() downgrades to the nearest 6×6×6 cube color:
  // rgb(215,119,87) (Claude orange) → idx 174 rgb(215,135,135) — washed-out salmon.
  if (process.env.TERM_PROGRAM === 'vscode' && chalk.level === 2) {
    chalk.level = 3
    return true
  }
  return false
}

export const CHALK_BOOSTED_FOR_XTERMJS = boostChalkLevelForXtermJs()

The comment is worth reading closely. Claude's brand orange rgb(215,119,87) becomes a washed-out salmon rgb(215,135,135) in 256-color mode because the cube quantization rounds in the wrong direction. Rather than accept brand-color corruption in VS Code, the code manually bumps chalk to level 3 (truecolor) when it detects TERM_PROGRAM=vscode.

Problem 2: tmux Drops Truecolor Backgrounds

function clampChalkLevelForTmux(): boolean {
  // tmux parses truecolor SGR (\e[48;2;r;g;bm) into its cell buffer correctly,
  // but its client-side emitter only re-emits truecolor to the outer terminal
  // if the outer terminal advertises Tc/RGB capability. Default tmux config
  // doesn't set this. Without it, backgrounds are simply dropped — bg=default
  // → black on dark profiles.
  // Clamping to level 2 makes chalk emit 256-color (\e[48;5;Nm),
  // which tmux passes through cleanly. grey93 (255) is visually identical.
  if (process.env.CLAUDE_CODE_TMUX_TRUECOLOR) return false
  if (process.env.TMUX && chalk.level > 2) {
    chalk.level = 2
    return true
  }
  return false
}

export const CHALK_CLAMPED_FOR_TMUX = clampChalkLevelForTmux()

The ordering of these two calls matters: boostChalkLevelForXtermJs runs first. If someone is running Claude Code inside VS Code's terminal inside tmux (common in remote dev setups), the boost happens first and the clamp re-clamps it back to 2. The clamp wins over the boost for tmux, because tmux's passthrough limitation is a hard constraint that can't be worked around without reconfiguring tmux itself. The escape hatch is CLAUDE_CODE_TMUX_TRUECOLOR=1, which skips the clamp for users who have correctly configured terminal-overrides ,*:Tc in their tmux config.

The colorize() Dispatch Table

With the chalk level set correctly, the actual color dispatch is a straightforward parser:

export const colorize = (
  str: string,
  color: string | undefined,
  type: ColorType,  // 'foreground' | 'background'
): string => {
  if (color.startsWith('ansi:')) {
    // Routes to chalk.red / chalk.bgRed etc.
    return type === 'foreground' ? chalk.red(str) : chalk.bgRed(str)
  }
  if (color.startsWith('#')) {
    return type === 'foreground'
      ? chalk.hex(color)(str)
      : chalk.bgHex(color)(str)
  }
  if (color.startsWith('ansi256')) {
    // Parses ansi256(N) → chalk.ansi256(N)
  }
  if (color.startsWith('rgb')) {
    // Parses rgb(r,g,b) → chalk.rgb(r,g,b)
  }
}

The string-prefix dispatch means the color format is self-describing. Any component that has resolved a theme token gets back a string that tells colorize exactly what kind of color it is — no separate type tag needed.

§5 styles.ts — Terminal Layout as TypeScript Types

The Styles type in ink/styles.ts is Claude Code's equivalent of a CSS properties object, but for terminal rendering. It covers layout (flexbox via Yoga), dimensions, borders, overflow, text wrapping, and color — all as readonly TypeScript properties.

export type TextStyles = {
  readonly color?: Color            // Raw color value, not a theme key
  readonly backgroundColor?: Color
  readonly dim?: boolean
  readonly bold?: boolean
  readonly italic?: boolean
  readonly underline?: boolean
  readonly strikethrough?: boolean
  readonly inverse?: boolean
}

// Color is a discriminated union of all supported formats:
export type Color = RGBColor | HexColor | Ansi256Color | AnsiColor
// where RGBColor = `rgb(${number},${number},${number})`
// and   AnsiColor = 'ansi:black' | 'ansi:red' | ... (16 ANSI names)

The key architectural decision here: TextStyles.color is always a raw Color value, never a theme key. The comment in the source is explicit: "Colors are raw values — theme resolution happens at the component layer." This means styles.ts and colorize.ts are completely unaware of themes. They are pure mechanics. Only the component layer (via design-system/color.ts) bridges from theme tokens to raw colors.

The Styles → Yoga Mapping

The default export of styles.ts is a function that applies a Styles object onto a LayoutNode (Yoga layout engine). This is what Ink calls when you write <Box flexDirection="row" padding={2}>:

const styles = (
  node: LayoutNode,
  style: Styles = {},
  resolvedStyle?: Styles,  // Full current style, for diff application
): void => {
  applyPositionStyles(node, style)
  applyOverflowStyles(node, style)
  applyMarginStyles(node, style)
  applyPaddingStyles(node, style)
  applyFlexStyles(node, style)
  applyDimensionStyles(node, style)
  applyDisplayStyles(node, style)
  applyBorderStyles(node, style, resolvedStyle)
  applyGapStyles(node, style)
}

The resolvedStyle parameter exists specifically for applyBorderStyles. When a style update is applied as a diff (only changed properties), borderStyle might be in the diff but borderTop might not be — because it didn't change. The resolved style carries the previous full value so the function can correctly set all four border edges even when the diff is partial.

One notable property: noSelect. This controls whether a box's cells are excluded from text selection in fullscreen mode. The 'from-left-edge' variant extends the exclusion from column 0 to the box's right edge for every row — specifically designed so that clicking and dragging over a diff panel doesn't accidentally copy line-number prefixes and diff sigils into the clipboard.

§6 design-system/color.ts — Bridging Themes to Raw Colors

This file is tiny but it is the architectural glue. It is the only place where theme key strings are resolved to raw color values:

export function color(
  c: keyof Theme | Color | undefined,
  theme: ThemeName,
  type: ColorType = 'foreground',
): (text: string) => string {
  return text => {
    if (!c) return text

    // Raw color values bypass theme lookup entirely
    if (
      c.startsWith('rgb(') || c.startsWith('#') ||
      c.startsWith('ansi256(') || c.startsWith('ansi:')
    ) {
      return colorize(text, c, type)
    }

    // Theme key → raw color → chalk output
    return colorize(text, getTheme(theme)[c as keyof Theme], type)
  }
}

The return value is a curried function, not a string. This means components can create colorizers once (e.g., at the top of a render function) and reuse them across multiple text strings, avoiding repeated theme lookups. The check for raw color prefixes means you can pass either a theme key like "claude" or a raw color like "rgb(215,119,87)" — both work transparently.

§7 The /theme and /color Commands

The /theme Command

The /theme command renders a full interactive ThemePicker component inside a Pane (wrapped with color="permission" — which is the blue/purple permission-request color, making the picker visually distinct from normal output):

// commands/theme/theme.tsx
export const call: LocalJSXCommandCall = async (onDone, _context) => {
  return <ThemePickerCommand onDone={onDone} />
}

function ThemePickerCommand({ onDone }: Props) {
  const [, setTheme] = useTheme()

  return (
    <Pane color="permission">
      <ThemePicker
        onThemeSelect={setting => {
          setTheme(setting)
          onDone(`Theme set to ${setting}`)
        }}
        onCancel={() => onDone('Theme picker dismissed', { display: 'system' })}
        skipExitHandling={true}
      />
    </Pane>
  )
}

The ThemePicker component itself (in components/ThemePicker.tsx) provides live preview — you can arrow through themes and see the UI re-render before committing. This works via a usePreviewTheme() hook that sets a temporary theme state distinct from the saved setting. Pressing Escape cancels and restores the previous theme; pressing Enter saves it.

The /color Command

The /color command is for sub-agent sessions only — it sets the color of the prompt bar for the current session, creating visual differentiation when multiple Claude Code agents are running simultaneously:

// commands/color/color.ts
export async function call(onDone, context, args) {
  // Teammates cannot set their own color — only the team leader assigns them
  if (isTeammate()) {
    onDone('Cannot set color: This session is a swarm teammate...', { display: 'system' })
    return null
  }

  const colorArg = args.trim().toLowerCase()

  // 'default', 'reset', 'none', 'gray', 'grey' all reset to gray
  if (RESET_ALIASES.includes(colorArg)) {
    await saveAgentColor(sessionId, 'default', fullPath)
    // Updates AppState for immediate effect
    context.setAppState(prev => ({
      ...prev,
      standaloneAgentContext: { ...prev.standaloneAgentContext, color: undefined }
    }))
    return null
  }

  // Valid colors: AGENT_COLORS = ['red','blue','green','yellow','purple','orange','pink','cyan']
  await saveAgentColor(sessionId, colorArg, fullPath)
  context.setAppState(prev => ({
    ...prev,
    standaloneAgentContext: { ...prev.standaloneAgentContext, color: colorArg }
  }))
}

§8 AgentColorManager — Sub-agent Visual Identity

In multi-agent (swarm) sessions, Claude Code needs to visually distinguish agents from each other. The agentColorManager.ts handles the mapping from agent type strings to theme color slots:

export const AGENT_COLORS: readonly AgentColorName[] = [
  'red', 'blue', 'green', 'yellow',
  'purple', 'orange', 'pink', 'cyan'
]

export const AGENT_COLOR_TO_THEME_COLOR = {
  red:    'red_FOR_SUBAGENTS_ONLY',
  blue:   'blue_FOR_SUBAGENTS_ONLY',
  // ... maps human-readable name → Theme key
} as const satisfies Record<AgentColorName, keyof Theme>

satisfies 제약이 핵심입니다 — 상수의 타입을 Record<AgentColorName, keyof Theme>으로 확장하지 않으면서, 맵의 모든 항목이 Theme 타입의 유효한 키를 가리키는지 컴파일 타임에 보장합니다. 누군가 새 에이전트 색상을 추가하면서 Theme 타입에 해당 _FOR_SUBAGENTS_ONLY 슬롯을 추가하는 것을 잊으면 빌드가 실패합니다.

general-purpose 에이전트 타입은 getAgentColor에서 undefined를 반환합니다 — 의도적으로 색상이 없는데, 범용 세션은 시각적으로 차별화되지 않기 때문입니다. 코드 리뷰, 테스팅 등 특화된 에이전트 타입만 풀에서 색상이 할당됩니다.

§9 전체 색상 해석 데이터 흐름

§10 심층 분석

// Create a chalk instance with 256-color level for Apple Terminal
// Apple Terminal doesn't handle 24-bit color escape sequences well
const chalkForChart =
  env.terminal === 'Apple_Terminal'
    ? new Chalk({ level: 2 }) // 256 colors
    : chalk

export function themeColorToAnsi(themeColor: string): string {
  const rgbMatch = themeColor.match(/rgb\(\s?(\d+),\s?(\d+),\s?(\d+)\s?\)/)
  if (rgbMatch) {
    const colored = chalkForChart.rgb(r, g, b)('X')
    return colored.slice(0, colored.indexOf('X'))
  }
}

if (isTeammate()) {
  onDone('Cannot set color: This session is a swarm teammate.
Teammate colors are assigned by the team leader.', { display: 'system' })
  return null
}