Themes

Source: https://pi.dev/docs/latest/themes

Themes are JSON files defining TUI colors.

Locations

Built-in: dark, light
Global: ~/.pi/agent/themes/*.json
Project: .pi/themes/*.json (only after project trust)
Packages: themes/ directories or pi.themes entries in package.json
Settings: themes array
CLI: --theme <path> (repeatable) loads a theme file; --use-theme <name[/name]> selects the initial theme for one run

Disable discovery with --no-themes. Select via /settings or {"theme": "my-theme"}. On first run Pi detects the terminal background and defaults to dark or light. Editing the active custom theme file hot-reloads it for immediate feedback.

--use-theme light starts a run with that theme without changing the saved setting; --use-theme light/dark uses lightTheme/darkTheme syntax to follow terminal appearance. Picking another theme later in /settings applies immediately and saves normally.

Format

{
  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
  "name": "my-theme",
  "vars": { "primary": "#00aaff", "secondary": 242 },
  "colors": { "accent": "primary", "muted": "secondary", "text": "" }
}

name is required, must be unique, and must not contain /.
vars is optional — reusable colors referenced by name from colors.
colors must define all 51 required tokens. Optional tokens fall back: thinkingMax → thinkingXhigh, scrollbarThumb and searchMatchBg → selectedBg, searchMatchText → text.
$schema enables editor auto-completion and validation.

Color Tokens (51 required + 4 optional)

Core UI (11): accent, border, borderAccent, borderMuted, success, error, warning, muted, dim, text, thinkingText
Backgrounds & content (11 required + 3 optional): selectedBg, userMessageBg, userMessageText, customMessageBg, customMessageText, customMessageLabel, toolPendingBg, toolSuccessBg, toolErrorBg, toolTitle, toolOutput, plus optional scrollbarThumb (fullscreen scrollbar thumb), searchMatchBg, and searchMatchText (transcript search). Non-current search matches render searchMatchText on searchMatchBg with an underline; the current match reverses that pair and uses bold.
Markdown (10): mdHeading, mdLink, mdLinkUrl, mdCode, mdCodeBlock, mdCodeBlockBorder, mdQuote, mdQuoteBorder, mdHr, mdListBullet
Tool diffs (3): toolDiffAdded, toolDiffRemoved, toolDiffContext
Syntax (9): syntaxComment, syntaxKeyword, syntaxFunction, syntaxVariable, syntaxString, syntaxNumber, syntaxType, syntaxOperator, syntaxPunctuation
Thinking level borders (6 required + 1 optional): thinkingOff, thinkingMinimal, thinkingLow, thinkingMedium, thinkingHigh, thinkingXhigh, and optional thinkingMax
Bash mode (1): bashMode

HTML Export (optional)

{ "export": { "pageBg": "#18181e", "cardBg": "#1e1e24", "infoBg": "#3c3728" } }

Controls /export HTML output. If omitted, colors are derived from userMessageBg.

Color Values

Format	Example	Notes
Hex	`"#ff0000"`	6-digit RGB
256-color	`39`	xterm palette index 0–255
Variable	`"primary"`	Reference to a `vars` entry
Default	`""`	Terminal default color

256-color ranges: 0-15 basic ANSI (terminal-dependent), 16-231 the 6×6×6 RGB cube (16 + 36R + 6G + B), 232-255 grayscale.

Pi emits 24-bit RGB; older 256-color terminals get the nearest approximation. Check truecolor with echo $COLORTERM. In VS Code set terminal.integrated.minimumContrastRatio to 1 for accurate colors.

Tips

Dark terminals want bright saturated colors with higher contrast; light terminals want darker muted colors. Start from a base palette (Nord, Gruvbox, Tokyo Night) in vars and reference it consistently. Test against different message types, tool states, markdown, and long wrapped text. Built-in themes to copy: src/modes/interactive/theme/dark.json and light.json.