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
settings.json

Use /settings and select your theme from the menu

{
  "theme": "my-theme"
}

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

Creating a Custom Theme

Create File

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

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"
  }
}

Select Theme

Use /settings or edit settings.json

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 contrastLight 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

Package themes for others:

Create Package

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

Add Themes

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

Publish

npm publish

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"
}

Get Started

Core Concepts

Coding Agent

LLM API

Agent Core

UI Libraries

Additional Tools

Guides

Theme Locations

Selecting a Theme

Creating a Custom Theme

Theme Format

Color Tokens

Core UI (11 colors)

Backgrounds & Content (11 colors)

Markdown (10 colors)

Tool Diffs (3 colors)

Syntax Highlighting (9 colors)

Thinking Level Borders (6 colors)

Bash Mode (1 color)

HTML Export (optional)

Color Values

256-Color Palette

Terminal Compatibility

Theme Variables

Tips

VS Code Terminal

Example Themes

dark.json

light.json

Troubleshooting

Next Steps

Customization

Pi Packages

Build docs developers (and LLMs) love

Get Started

Core Concepts

Coding Agent

LLM API

Agent Core

UI Libraries

Additional Tools

Guides

Documentation Index

​Theme Locations

​Selecting a Theme

​Creating a Custom Theme

​Theme Format

​Color Tokens

​Core UI (11 colors)

​Backgrounds & Content (11 colors)

​Markdown (10 colors)

​Tool Diffs (3 colors)

​Syntax Highlighting (9 colors)

​Thinking Level Borders (6 colors)

​Bash Mode (1 color)

​HTML Export (optional)

​Color Values

​256-Color Palette

​Terminal Compatibility

​Theme Variables

​Tips

​VS Code Terminal

​Example Themes

dark.json

light.json

​Sharing Themes

​Troubleshooting

​Next Steps

Customization

Pi Packages

Build docs developers (and LLMs) love

Theme Locations

Selecting a Theme

Creating a Custom Theme

Theme Format

Color Tokens

Core UI (11 colors)

Backgrounds & Content (11 colors)

Markdown (10 colors)

Tool Diffs (3 colors)

Syntax Highlighting (9 colors)

Thinking Level Borders (6 colors)

Bash Mode (1 color)

HTML Export (optional)

Color Values

256-Color Palette

Terminal Compatibility

Theme Variables

Tips

VS Code Terminal

Example Themes

Sharing Themes

Troubleshooting

Next Steps