Themes

✓ Fresh · 2026-02-24

Pi supports visual themes that control the terminal UI appearance. Themes can be switched instantly and support hot-reload during development.

Built-in Themes

Pi ships with two built-in themes:

Theme	Description
dark	Dark background, light text (default)
light	Light background, dark text

Set the active theme in settings:

{
  "theme": "dark"
}

Or switch via the /settings command.

Custom Themes

Create custom themes as JSON files in theme directories.

Theme Directories

Directory	Scope
~/.pi/agent/themes/	Global (all projects)
.pi/themes/	Project-specific
Pi packages	Installed via pi install

Theme File Format

Themes are JSON files that define color tokens for different UI elements:

{
  "name": "ocean",
  "colors": {
    "background": "#0a1628",
    "foreground": "#e2e8f0",
    "accent": "#38bdf8",
    "error": "#ef4444",
    "warning": "#f59e0b",
    "success": "#22c55e",
    "muted": "#64748b",
    "border": "#1e293b"
  }
}

Hot Reload

Pi supports hot-reload for themes. When you modify the active theme file, Pi immediately applies the changes without restarting. This makes theme development a fast feedback loop:

1. Open your theme JSON in an editor
2. Make color changes
3. Save the file
4. Pi updates the UI instantly

Theme Cycling Extension

The community theme-cycler.ts extension adds keyboard shortcuts for rapid theme switching:

Shortcut	Action
Ctrl+X	Cycle to next theme
Ctrl+Q	Cycle to previous theme
/theme	Interactive theme selector

See IndyDevDan Extensions for installation details.

Sharing Themes

Bundle themes in a Pi package for sharing:

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

Install with:

pi install npm:my-pi-themes