Themes: customize Pi's terminal appearance

Themes are JSON files that define colors for Pi’s terminal UI. Pi ships with two built-in themes — dark and light — and auto-selects based on your terminal background on first run. You can create custom themes, switch between them via /settings, and edit the active theme file to see changes instantly.

Theme locations

Pi loads themes from these locations:

Location	Scope
Built-in	`dark`, `light`
`~/.pi/agent/themes/*.json`	Global (all projects)
`.pi/themes/*.json`	Project-local
`themes/` in Pi packages	Via installed packages

Add paths in settings.json:

{
  "themes": ["/path/to/my-themes/"]
}

Use --theme <path> on the CLI to load a theme for a single run. Disable theme discovery with --no-themes.

Selecting a theme

Switch themes via /settings in interactive mode, or set in settings.json:

{
  "theme": "my-theme"
}

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

Creating a custom theme

Create the theme file

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

Define all 51 color tokens

{
  "$schema": "https://raw.githubusercontent.com/earendil-works/pi-mono/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",
    "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",
    "bashMode": "#ffaa00"
  }
}

Select the theme

Run /settings in Pi and choose your new theme from the list.

The $schema field enables auto-completion and validation in editors that support JSON Schema.

Hot reload

When you modify the currently active custom theme file, Pi reloads it automatically. Changes apply immediately without restarting Pi or running /reload. This makes it easy to iterate on colors while Pi is running.

Theme format

{
  "$schema": "...",
  "name": "my-theme",
  "vars": {
    "blue": "#0066cc",
    "gray": 242
  },
  "colors": {
    "accent": "blue",
    "muted": "gray",
    "text": ""
  }
}

name is required and must be unique.
vars is optional. Define reusable color values and reference them by name in colors.
colors must define all 51 required tokens. There are no optional colors.

Color tokens

Every theme must define all 51 color tokens across these categories:

Core UI (11 tokens)

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

Backgrounds and content (11 tokens)

Token	Purpose
`selectedBg`	Selected line background
`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 tokens)

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 tokens)

Token	Purpose
`toolDiffAdded`	Added lines
`toolDiffRemoved`	Removed lines
`toolDiffContext`	Context lines

Syntax highlighting (9 tokens)

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 tokens)

The editor border color indicates the active thinking level. 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

Bash mode (1 token)

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

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 foreground or background

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

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

HTML export colors

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

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

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 it 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.

Add a themes/ directory to a Pi package to share themes via npm or git:

{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": {
    "themes": ["./themes"]
  }
}

Pi packages

Bundle and share themes via npm or git.

Extensions

Access and switch themes programmatically from extensions.

Get Started

Using Pi

Customization

Programmatic Usage

Themes: customize Pi's terminal appearance

Theme locations

Selecting a theme

Creating a custom theme

Hot reload

Theme format

Color tokens

Color values

HTML export colors

Tips

Pi packages

Extensions

Build docs developers (and LLMs) love

Get Started

Using Pi

Customization

Programmatic Usage

Documentation Index

​Theme locations

​Selecting a theme

​Creating a custom theme

​Hot reload

​Theme format

​Color tokens

​Color values

​HTML export colors

​Tips

​Sharing themes

​Related

Pi packages

Extensions

Build docs developers (and LLMs) love

Theme locations

Selecting a theme

Creating a custom theme

Hot reload

Theme format

Color tokens

Color values

HTML export colors

Tips

Sharing themes

Related