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

Creating a Custom Theme¶

1. Create a theme file:

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

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

{
  "$schema": "https://raw.githubusercontent.com/badlogic/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"
  }
}

1. 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/badlogic/pi-mono/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 and must be unique.
• vars is optional. Define reusable colors here, then reference them in colors.
• colors must define all 51 required tokens.

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

Color Tokens¶

Every theme must define all 51 color tokens. There are no optional colors.

Core UI (11 colors)¶

Backgrounds & Content (11 colors)¶

Markdown (10 colors)¶

Tool Diffs (3 colors)¶

Syntax Highlighting (9 colors)¶

Thinking Level Borders (6 colors)¶

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

Bash Mode (1 color)¶

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:

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