packages/coding-agent/docs/themes.md

pi can create themes. Ask it to build one for your setup.

Themes

Themes are JSON files that define colors for the TUI.

Table of Contents

• Locations
• Selecting a Theme
• Creating a Custom Theme
• Theme Format
• Color Tokens
• Color Values
• Tips

Locations

Pi loads themes from:

• Built-in: dark, light
• Global: ~/.pi/agent/themes/*.json
• Project: .pi/themes/*.json (only after the project is trusted)
• Packages: themes/ directories or pi.themes entries in package.json
• Settings: themes array with files or directories
• CLI: --theme <path> (repeatable)

Disable discovery with --no-themes.

Selecting a Theme

Select a theme via /settings or in settings.json:

{
  "theme": "my-theme"
}

On first run, pi detects your terminal background and defaults to dark or light.

Initial Theme

Start an interactive run with a theme without changing the saved setting:

pi --use-theme light

To follow terminal appearance, use lightTheme/darkTheme syntax:

pi --use-theme light/dark

The CLI value is the initial theme for that run. Choosing another theme later in /settings applies it immediately and saves it normally.

Creating a Custom Theme

1. Create a theme file:

mkdir -p ~/.pi/agent/themes
vim ~/.pi/agent/themes/my-theme.json

2. Define the theme with all required colors (see Color Tokens):

{
  "$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",
    "border": "primary",
    "borderAccent": "#00ffff",
    "borderMuted": "secondary",
    "success": "#00ff00",
    "error": "#ff0000",
    "warning": "#ffff00",
    "muted": "secondary",
    "dim": 240,
    "text": "",
    "thinkingText": "secondary",
    "selectedBg": "#2d2d30",
    "scrollbarTrack": "secondary",
    "scrollbarThumb": "",
    "searchMatchBg": "#2d2d30",
    "searchMatchText": "",
    "userMessageBg": "#2d2d30",
    "userMessageText": "",
    "customMessageBg": "#2d2d30",
    "customMessageText": "",
    "customMessageLabel": "primary",
    "toolPendingBg": "#1e1e2e",
    "toolSuccessBg": "#1e2e1e",
    "toolErrorBg": "#2e1e1e",
    "toolTitle": "primary",
    "toolOutput": "",
    "mdHeading": "#ffaa00",
    "mdLink": "primary",
    "mdLinkUrl": "secondary",
    "mdCode": "#00ffff",
    "mdCodeBlock": "",
    "mdCodeBlockBorder": "secondary",
    "mdQuote": "secondary",
    "mdQuoteBorder": "secondary",
    "mdHr": "secondary",
    "mdListBullet": "#00ffff",
    "toolDiffAdded": "#00ff00",
    "toolDiffRemoved": "#ff0000",
    "toolDiffContext": "secondary",
    "syntaxComment": "secondary",
    "syntaxKeyword": "primary",
    "syntaxFunction": "#00aaff",
    "syntaxVariable": "#ffaa00",
    "syntaxString": "#00ff00",
    "syntaxNumber": "#ff00ff",
    "syntaxType": "#00aaff",
    "syntaxOperator": "primary",
    "syntaxPunctuation": "secondary",
    "thinkingOff": "secondary",
    "thinkingMinimal": "primary",
    "thinkingLow": "#00aaff",
    "thinkingMedium": "#00ffff",
    "thinkingHigh": "#ff00ff",
    "thinkingXhigh": "#ff0000",
    "thinkingMax": "#ff0088",
    "bashMode": "#ffaa00"
  }
}

3. Select the theme via /settings.

Hot reload: When you edit the currently active custom theme file, pi reloads it automatically for immediate visual feedback.

Theme Format

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

• name is required, must be unique, and must not contain /.
• vars is optional. Define reusable colors here, then reference them in colors.
• colors must define all 53 required tokens. thinkingMax and the two search highlight tokens are optional and use the fallbacks listed below.

The $schema field enables editor auto-completion and validation.

Color Tokens

Every theme must define all 53 required color tokens. The optional tokens preserve compatibility with existing themes: thinkingMax falls back to thinkingXhigh, searchMatchBg falls back to selectedBg, and searchMatchText falls back to text. Other search matches use searchMatchText on searchMatchBg with an underline; the current match reverses that foreground/background pair and uses bold text.

Core UI (13 colors)

Token	Purpose
accent	Primary accent (logo, selected items, cursor)
border	Normal borders
borderAccent	Highlighted borders
borderMuted	Subtle borders (editor)
success	Success states
error	Error states
warning	Warning states
muted	Secondary text
dim	Tertiary text
text	Default text (usually "")
thinkingText	Thinking block text
scrollbarTrack	Fullscreen scrollbar track foreground
scrollbarThumb	Fullscreen scrollbar thumb foreground, shared by normal and expanded states

Backgrounds & Content (11 required, 2 optional)

Token	Purpose
selectedBg	Selected line background
searchMatchBg	Transcript search match background and current-match text; optional, falls back to selectedBg
searchMatchText	Transcript search match text and current-match background; optional, falls back to text
userMessageBg	User message background
userMessageText	User message text
customMessageBg	Extension message background
customMessageText	Extension message text
customMessageLabel	Extension message label
toolPendingBg	Tool box (pending)
toolSuccessBg	Tool box (success)
toolErrorBg	Tool box (error)
toolTitle	Tool title
toolOutput	Tool output text

Markdown (10 colors)

Token	Purpose
mdHeading	Headings
mdLink	Link text
mdLinkUrl	Link URL
mdCode	Inline code
mdCodeBlock	Code block content
mdCodeBlockBorder	Code block fences
mdQuote	Blockquote text
mdQuoteBorder	Blockquote border
mdHr	Horizontal rule
mdListBullet	List bullets

Tool Diffs (3 colors)

Token	Purpose
toolDiffAdded	Added lines
toolDiffRemoved	Removed lines
toolDiffContext	Context lines

Syntax Highlighting (9 colors)

Token	Purpose
syntaxComment	Comments
syntaxKeyword	Keywords
syntaxFunction	Function names
syntaxVariable	Variables
syntaxString	Strings
syntaxNumber	Numbers
syntaxType	Types
syntaxOperator	Operators
syntaxPunctuation	Punctuation

Thinking Level Borders (6 required, 1 optional)

Editor border colors indicating thinking level (visual hierarchy from subtle to prominent):

Token	Purpose
thinkingOff	Thinking off
thinkingMinimal	Minimal thinking
thinkingLow	Low thinking
thinkingMedium	Medium thinking
thinkingHigh	High thinking
thinkingXhigh	Extra high thinking
thinkingMax	Maximum thinking; optional, falls back to thinkingXhigh

Bash Mode (1 color)

Token	Purpose
bashMode	Editor border in bash mode (! prefix)

HTML Export (optional)

The export section controls colors for /export HTML output. If omitted, colors are derived from userMessageBg.

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

Color Values

Four formats are supported:

Format	Example	Description
Hex	"#ff0000"	6-digit hex RGB
256-color	39	xterm 256-color palette index (0-255)
Variable	"primary"	Reference to a vars entry
Default	""	Terminal's default color

256-Color Palette

• 0-15: Basic ANSI colors (terminal-dependent)
• 16-231: 6×6×6 RGB cube (16 + 36×R + 6×G + B where R,G,B are 0-5)
• 232-255: Grayscale ramp

Terminal Compatibility

Pi uses 24-bit RGB colors. Most modern terminals support this (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). For older terminals with only 256-color support, pi falls back to the nearest approximation.

Check truecolor support:

echo $COLORTERM  # Should output "truecolor" or "24bit"

Tips

Dark terminals: Use bright, saturated colors with higher contrast.

Light terminals: Use darker, muted colors with lower contrast.

Color harmony: Start with a base palette (Nord, Gruvbox, Tokyo Night), define it in vars, and reference consistently.

Testing: Check your theme with different message types, tool states, markdown content, and long wrapped text.

VS Code: Set terminal.integrated.minimumContrastRatio to 1 for accurate colors.

Examples

See the built-in themes:

• dark.json
• light.json