Themes

Customizing Pi’s terminal UI colors and appearance with JSON themes

Pi can create themes for you. Just ask it to build one for your setup.

Themes are JSON files that define colors for the TUI (Terminal User Interface). Pi supports 24-bit RGB colors and includes built-in dark and light themes.

Theme Locations

Pi loads themes from:

Built-in:

• dark, light

Global:

• ~/.pi/agent/themes/*.json

Project:

• .pi/themes/*.json

Packages:

• themes/ directories in pi packages
• 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

Interactive

Use /settings and select your theme from the menu

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 File

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

   {
     "$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"
     }
   }
   
3. Select Theme

   Use /settings or edit settings.json

4. Hot Reload

   Edit the active theme file - Pi reloads it automatically!

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": "",
    // ... all 51 color tokens
  }
}

Fields:

• name - Required, must be unique
• vars - Optional reusable colors
• colors - Required, must define all 51 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)

accent · color

Primary accent (logo, selected items, cursor)

border · color

Normal borders

borderAccent · color

Highlighted borders

borderMuted · color

Subtle borders (editor)

success · color

Success states

error · color

Error states

warning · color

Warning states

muted · color

Secondary text

dim · color

Tertiary text

text · color

Default text (usually "")

thinkingText · color

Thinking block text

Backgrounds & Content (11 colors)

selectedBg · color

Selected line background

userMessageBg · color

User message background

userMessageText · color

User message text

customMessageBg · color

Extension message background

customMessageText · color

Extension message text

customMessageLabel · color

Extension message label

toolPendingBg · color

Tool box (pending)

toolSuccessBg · color

Tool box (success)

toolErrorBg · color

Tool box (error)

toolTitle · color

Tool title

toolOutput · color

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

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

Bash Mode (1 color)

bashMode · color

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 (macOS)
• Kitty (Linux/macOS)
• WezTerm (cross-platform)
• Windows Terminal
• VS Code integrated terminal

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"

Theme Variables

Use vars to define reusable colors:

{
  "vars": {
    "nord0": "#2e3440",
    "nord1": "#3b4252",
    "nord8": "#88c0d0",
    "nord10": "#5e81ac"
  },
  "colors": {
    "accent": "nord8",
    "border": "nord10",
    "muted": "nord1",
    "selectedBg": "nord0",
    // ...
  }
}

This makes it easy to:

• Maintain color harmony
• Try different base palettes
• Update colors globally

Tips

Start with a base palette

Use established color palettes for harmony:

• Nord
• Gruvbox
• Tokyo Night
• Dracula
• Solarized

Define them in vars and reference consistently.

Consider your terminal background

Dark terminals: Use bright, saturated colors with higher contrast

Light terminals: Use darker, muted colors with lower contrast

Test thoroughly

Check your theme with:

• Different message types (user, assistant, custom)
• All tool states (pending, success, error)
• Markdown content (headings, code, quotes)
• Long wrapped text
• Thinking blocks at different levels

Use hot reload

Select your theme, then edit the JSON file. Changes appear immediately without restarting Pi.

Match your terminal

For best results, use colors that harmonize with your terminal’s color scheme.

VS Code Terminal

For accurate colors in VS Code, set:

{
  "terminal.integrated.minimumContrastRatio": 1
}

This disables automatic contrast adjustment that can alter your theme colors.

Example Themes

See the built-in themes for reference:

dark.json

Built-in dark theme source

light.json

Built-in light theme source

Sharing Themes

Package themes for others:

1. Create Package

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

   my-themes/
   ├── package.json
   └── themes/
       ├── nord.json
       ├── gruvbox.json
       └── tokyo-night.json
   
3. Publish

   npm publish
   
4. Users Install

   pi install npm:my-themes
   

See Pi Packages for full details.

Troubleshooting

Colors look washed out

Your terminal may not support 24-bit color. Check $COLORTERM:

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

If not supported, consider switching to a modern terminal.

Theme not appearing

Ensure:

• File is in a discovered location
• Filename ends with .json
• JSON is valid (use the $schema for validation)
• Theme name is unique
• All 51 color tokens are defined

Hot reload not working

Hot reload only works for the currently active theme. If you’re editing a different theme, select it first via /settings.

Validation errors

Use the $schema field to enable validation in your editor:

{
  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json"
}

Next Steps

Customization

Explore all customization options

Pi Packages

Package and share themes via npm or git