16  Themes

16.1 Overview

Pi themes control the visual appearance of the terminal interface. Themes define colors for syntax highlighting, UI elements, message types, and the overall look and feel of the TUI.

16.2 Built-in Themes

Pi ships with several built-in themes:

Theme Style Description
default-dark Dark Default dark theme with balanced contrast
default-light Light Default light theme for bright terminals
midnight Dark Deep blue/black background with bright accents
nord Dark Nord color palette inspired by Scandinavian landscapes
solarized-dark Dark Solarized dark palette for reduced eye strain
solarized-light Light Solarized light palette
dracula Dark Popular Dracula color scheme
gruvbox-dark Dark Gruvbox dark palette with warm tones
gruvbox-light Light Gruvbox light palette
catppuccin-mocha Dark Catppuccin Mocha flavor
catppuccin-latte Light Catppuccin Latte flavor
tokyo-night Dark Tokyo Night inspired palette
github-dark Dark GitHub Dark theme
github-light Light GitHub Light theme

16.2.1 Selecting a Theme

In interactive mode:

/settings

Navigate to the Theme option and select from the list.

Or via settings:

// ~/.pi/agent/settings.json
{
  "theme": "nord"
}

Or via environment variable:

export PI_THEME=nord
pi

16.2.2 Cycling Themes

There is no built-in theme cycling shortcut, but you can quickly switch via /settings.

16.3 Custom Themes

Create custom themes as JSON files in:

Location Scope
~/.pi/agent/themes/*.json Global
.pi/themes/*.json Project-local
Via settings.json themes array Additional paths

16.3.1 Theme JSON Format

{
  "name": "my-custom-theme",
  "type": "dark",
  "colors": {
    "background": "#1a1b26",
    "foreground": "#a9b1d6",
    "cursor": "#c0caf5",
    "selection": "#33467c",
    "border": "#3b4261",
    "borderFocused": "#7aa2f7",
    "borderMuted": "#292e42",
    "primary": "#7aa2f7",
    "secondary": "#bb9af7",
    "accent": "#e0af68",
    "success": "#9ece6a",
    "warning": "#e0af68",
    "error": "#f7768e",
    "muted": "#565f89",
    "dimmed": "#414868",
    "link": "#7dcfff",
    "diffAdded": "#9ece6a",
    "diffRemoved": "#f7768e",
    "diffContext": "#a9b1d6",
    "diffAddedDimmed": "#414868",
    "diffRemovedDimmed": "#414868"
  },
  "syntax": {
    "keyword": "#bb9af7",
    "function": "#7aa2f7",
    "string": "#9ece6a",
    "number": "#ff9e64",
    "comment": "#565f89",
    "variable": "#c0caf5",
    "type": "#2ac3de",
    "operator": "#89ddff",
    "punctuation": "#a9b1d6",
    "tag": "#f7768e",
    "attribute": "#e0af68",
    "property": "#73daca",
    "regex": "#b4f9f8"
  },
  "messageColors": {
    "user": "#7aa2f7",
    "assistant": "#9ece6a",
    "toolCall": "#e0af68",
    "toolResult": "#73daca",
    "error": "#f7768e",
    "notification": "#bb9af7",
    "warning": "#e0af68",
    "success": "#9ece6a"
  }
}

16.4 Theme Color Variables

16.4.1 Core Colors

Variable Description
background Main background color
foreground Default text color
cursor Cursor color
selection Selected text background
border Default border color (editor, panels)
borderFocused Focused element border color
borderMuted Dimmed border color
primary Primary accent color
secondary Secondary accent color
accent Tertiary accent color

16.4.2 Status Colors

Variable Description
success Success messages and indicators
warning Warning messages and indicators
error Error messages and indicators
muted Muted/secondary text
dimmed Very dim text (metadata, hints)
link Links and URLs

16.4.3 Diff Colors

Variable Description
diffAdded Added lines in diffs
diffRemoved Removed lines in diffs
diffContext Unchanged lines in diffs
diffAddedDimmed Dimmed added lines
diffRemovedDimmed Dimmed removed lines

16.4.4 Syntax Highlighting

Variable Description
keyword Language keywords (if, for, return, etc.)
function Function names
string String literals
number Numeric literals
comment Code comments
variable Variable names
type Type/class names
operator Operators (+, -, =, etc.)
punctuation Punctuation (brackets, commas, etc.)
tag HTML/XML tags
attribute HTML/XML attributes
property Object properties
regex Regular expressions

16.4.5 Message Colors

Variable Description
user User message accent
assistant Assistant message accent
toolCall Tool call accent
toolResult Tool result accent
error Error message accent
notification Notification accent
warning Warning message accent
success Success message accent

16.5 Creating a Custom Theme

16.5.1 Step 1: Choose Base Colors

Start by picking a palette. Popular palette generators:

16.5.2 Step 2: Create the Theme File

mkdir -p ~/.pi/agent/themes

Create ~/.pi/agent/themes/my-theme.json:

{
  "name": "my-theme",
  "type": "dark",
  "colors": {
    "background": "#0d1117",
    "foreground": "#c9d1d9",
    "cursor": "#58a6ff",
    "selection": "#264f78",
    "border": "#30363d",
    "borderFocused": "#58a6ff",
    "borderMuted": "#21262d",
    "primary": "#58a6ff",
    "secondary": "#bc8cff",
    "accent": "#d29922",
    "success": "#3fb950",
    "warning": "#d29922",
    "error": "#f85149",
    "muted": "#8b949e",
    "dimmed": "#484f58",
    "link": "#58a6ff"
  },
  "syntax": {
    "keyword": "#ff7b72",
    "function": "#d2a8ff",
    "string": "#a5d6ff",
    "number": "#79c0ff",
    "comment": "#8b949e",
    "variable": "#c9d1d9",
    "type": "#ffa657",
    "operator": "#ff7b72",
    "punctuation": "#c9d1d9",
    "tag": "#7ee787",
    "attribute": "#79c0ff",
    "property": "#79c0ff",
    "regex": "#a5d6ff"
  },
  "messageColors": {
    "user": "#58a6ff",
    "assistant": "#3fb950",
    "toolCall": "#d29922",
    "toolResult": "#79c0ff",
    "error": "#f85149",
    "notification": "#bc8cff",
    "warning": "#d29922",
    "success": "#3fb950"
  }
}

16.5.3 Step 3: Apply the Theme

// ~/.pi/agent/settings.json
{
  "theme": "my-theme"
}

Or use /settings in interactive mode.

16.5.4 Step 4: Reload

Use /reload to reload themes without restarting Pi.

16.6 Theme Inheritance

Custom themes inherit from the built-in defaults. Any unspecified color variable falls back to the default theme value. This means you can create a minimal theme that only overrides a few colors:

{
  "name": "minimal-override",
  "type": "dark",
  "colors": {
    "primary": "#ff79c6",
    "secondary": "#8be9fd",
    "accent": "#bd93f9"
  }
}

All other colors use the default dark theme values.

16.7 Terminal Compatibility

16.7.1 True Color Support

Pi themes use 24-bit true color (hex values). Most modern terminals support true color:

  • iTerm2 (macOS)
  • Windows Terminal (Windows)
  • GNOME Terminal (Linux)
  • Alacritty
  • Kitty
  • WezTerm
  • Ghostty

If your terminal does not support true color, colors may appear incorrectly.

16.7.2 Checking Terminal Color Support

# Check if terminal supports true color
echo -e "\033[38;2;255;100;0mTRUE COLOR TEST\033[0m"

If the text appears orange, your terminal supports true color.

Note

Ensure your TERM environment variable is set correctly (e.g., xterm-256color or screen-256color) for proper color rendering.