Creating themes

One JSON file, 51 color tokens, hot reload. Restyle every part of pi's TUI.

Anatomy of a theme

A pi theme is a single JSON file. Define reusable colors in vars, then assign all 51 required tokens in colors (only thinkingMax is optional). Values can be hex codes, xterm-256 palette indices (0–255), references to your vars, or an empty string to fall back to the terminal default.

{
  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
  "name": "my-theme",
  "vars": {
    "bg": "#0a0a0a",
    "accent": "#fab283",
    "green": "#7fd88f",
    "red": "#e06c75"
  },
  "colors": {
    "accent": "accent",
    "border": "#1f1f1f",
    "success": "green",
    "error": "red",
    "text": "#eeeeee",
    "userMessageBg": "#141414",
    "toolDiffAdded": "green",
    "toolDiffRemoved": "red"
  }
}

(Abbreviated — the $schema line gives you completion and validation for all 51 tokens in your editor.)

The token groups

Workflow

1. Copy an existing theme — the gallery links to real files, or start from pi’s built-in dark/light.
2. Save yours to ~/.pi/agent/themes/my-theme.json (or .pi/themes/ in a project).
3. Run pi and pick it via /settings, or set "theme": "my-theme" in settings.json.
4. Edit the file — custom themes hot-reload while pi is running, so you can tune colors live.

You can also try a theme file directly without installing it:

pi --theme ./my-theme.json

Tips from the themes in our gallery

• Keep muted/dim genuinely low-contrast — most of pi’s chrome uses them, and loud values make the UI shouty.
• Diff colors (toolDiffAdded/toolDiffRemoved) are the ones you’ll see most while coding; test them against your toolSuccessBg.
• xterm indices are handy if you want the theme to inherit the user’s terminal palette instead of forcing exact hexes.

Share it

Put the JSON in a package’s themes/ directory, publish, and it installs with everything else — see Publishing packages. Then submit it here and we’ll render a live preview in the gallery from your actual theme file.