Pi Agent Theme Customization
Pi Agent supports customizing terminal interface colors.
This chapter covers how to use built-in themes and create custom themes.
Theme Overview
Pi Agent uses JSON-format theme files to define all colors in the TUI interface.
Each theme needs to define51 required tokens + 4 optional tokens (thinkingMax, scrollbarThumb, searchMatchBg, searchMatchText), covering colors for various interface elements such as core UI, message backgrounds, Markdown rendering, syntax highlighting, and editor borders.
Built-in Themes
Pi Agent ships with two built-in themes:
| Theme Name | Applicable Scenario | Description |
|---|---|---|
| dark | Dark terminal background (default) | Suitable for dark terminals used by most developers |
| light | Light terminal background | Suitable for terminals with light themes |
On first launch, Pi Agent automatically detects your terminal background color and selects dark or light.
In interactive mode, type /settings and switch directly in the theme options:
/settings
You can also write the theme field in settings.json and change the value of theme to the theme name:
Example
"theme": "light"
}
Creating Custom Themes
First, create the theme directory and file:
mkdir -p ~/.pi/agent/themes vim ~/.pi/agent/themes/my-theme.json
Then define the theme file. The following is a complete custom theme example:
Example
"name": "my-theme",
"vars": {
"blue": "#0066cc",
"gray": 242,
"orange": "#ffaa00",
"green": "#0055AA"
},
"colors": {
"accent": "blue",
"border": "blue",
"borderAccent": "#00ffff",
"borderMuted": "gray",
"success": "green",
"error": "#ff0000",
"warning": "#ffff00",
"muted": "gray",
"dim": 240,
"text": "",
"thinkingText": "gray",
"selectedBg": "#2d2d30",
"userMessageBg": "#2d2d30",
"userMessageText": "",
"customMessageBg": "#2d2d30",
"customMessageText": "",
"customMessageLabel": "blue",
"toolPendingBg": "#1e1e2e",
"toolSuccessBg": "#1e2e1e",
"toolErrorBg": "#2e1e1e",
"toolTitle": "blue",
"toolOutput": "",
"mdHeading": "orange",
"mdLink": "blue",
"mdLinkUrl": "gray",
"mdCode": "#00ffff",
"mdCodeBlock": "",
"mdCodeBlockBorder": "gray",
"mdQuote": "gray",
"mdQuoteBorder": "gray",
"mdHr": "gray",
"mdListBullet": "#00ffff",
"toolDiffAdded": "green",
"toolDiffRemoved": "#ff0000",
"toolDiffContext": "gray",
"syntaxComment": "gray",
"syntaxKeyword": "blue",
"syntaxFunction": "#00aaff",
"syntaxVariable": "orange",
"syntaxString": "green",
"syntaxNumber": "#ff00ff",
"syntaxType": "#00aaff",
"syntaxOperator": "blue",
"syntaxPunctuation": "gray",
"thinkingOff": "gray",
"thinkingMinimal": "blue",
"thinkingLow": "#00aaff",
"thinkingMedium": "#00ffff",
"thinkingHigh": "#ff00ff",
"thinkingXhigh": "#ff0000",
"thinkingMax": "#ff0088",
"bashMode": "orange"
}
}
Then enable your theme in settings.json:
Example
"theme": "my-theme"
}
When you edit the custom theme file currently in use, Pi Agent automatically hot-reloads the theme, letting you see changes immediately without any action.
Theme File Loading Locations
Pi Agent looks for theme files in the following locations.
Themes placed in different locations have different visibility scopes and loading conditions.
| Location | Scope |
|---|---|
| Built-in | dark, light always available |
| ~/.pi/agent/themes/*.json | Global themes, available to all projects |
| .pi/themes/*.json | Project themes, loaded only after the project is trusted |
| Pi Packages | themes/ directory in the package |
| --theme path | Temporarily loaded via command line |
Color Value Formats
Pi Agent supports four color value formats:
| Format | Example | Description |
|---|---|---|
| Hex color | "#ff0000" | 6-digit hexadecimal RGB color |
| 256-color palette | 39 | xterm 256-color palette index (0-255) |
| Variable reference | "blue" | References a variable defined in vars |
| Terminal default color | "" | Uses the terminal's default foreground/background color |
The vars section is used to define reusable color variables, referenced by name in colors.
After extracting the primary colors into variables, changing the color scheme only requires editing one place, making theme maintenance easier.
Color Token Categories
Each token in colors corresponds to the color of a category of elements in the interface.
Below, all tokens are divided into six categories by purpose for easy reference.
Core UI (11)
This group controls the colors of basic interface elements such as the editor and status bar.
| Token | Purpose |
|---|---|
| accent | Primary color (Logo, selected items, cursor) |
| border | Normal border |
| borderAccent | Highlight border |
| borderMuted | Soft border for the editor area |
| success | Success status |
| error | Error status |
| warning | Warning status |
| muted | Secondary text |
| dim | Tertiary text (even less prominent) |
| text | Default text color (usually left empty) |
| thinkingText | AI reasoning process text |
Background & Content (11 required + 3 optional)
This group controls the background and text of selected items, message bubbles, and tool output areas.
| Token | Purpose |
|---|---|
| selectedBg | Selected item background (current entry in the list) |
| userMessageBg | User message background |
| userMessageText | User message text |
| customMessageBg | Expanded message background |
| customMessageText | Expanded message text |
| customMessageLabel | Title tag color for expanded messages |
| toolPendingBg | Tool executing background |
| toolSuccessBg | Tool execution success background |
| toolErrorBg | Tool execution failure background |
| toolTitle | Tool card title text |
| toolOutput | Tool output text |
| scrollbarThumb | Fullscreen scrollbar thumb color (optional, falls back to selectedBg if not defined) |
| searchMatchBg | Search match background (optional, falls back to selectedBg if not defined) |
| searchMatchText | Search match text (optional, falls back to text if not defined) |
Markdown Rendering (10)
This group controls the colors of Markdown elements in AI replies.
| Token | Purpose |
|---|---|
| mdHeading | Heading |
| mdLink | Link text |
| mdLinkUrl | Link URL address |
| mdCode | Inline code |
| mdCodeBlock | Code block content |
| mdCodeBlockBorder | Code block border |
| mdQuote | Blockquote text |
| mdQuoteBorder | Blockquote border |
| mdHr | Divider |
| mdListBullet | List marker |
Syntax Highlighting (9)
This group controls the syntax highlighting colors within code blocks.
| Token | Purpose |
|---|---|
| syntaxComment | Comment |
| syntaxKeyword | Keyword |
| syntaxFunction | Function name |
| syntaxVariable | Variable name |
| syntaxString | String |
| syntaxNumber | Number |
| syntaxType | Type |
| syntaxOperator | Operator |
| syntaxPunctuation | Punctuation |
Reasoning Level Borders (7)
This group controls the indicator color of the current reasoning level on the editor border.
| Token | Corresponding Level |
|---|---|
| thinkingOff | Reasoning off |
| thinkingMinimal | Minimum reasoning |
| thinkingLow | Low reasoning |
| thinkingMedium | Medium reasoning |
| thinkingHigh | High reasoning |
| thinkingXhigh | Extra-high reasoning |
| thinkingMax | Maximum reasoning (optional) |
thinkingMax is an optional token. If not defined, it falls back to the thinkingXhigh color.
Diff & Bash Colors (4)
This group controls diff highlighting and bash mode prompt colors — the ones you see most often when editing code.
| Token | Purpose |
|---|---|
| toolDiffAdded | diff added lines (usually green) |
| toolDiffRemoved | diff removed lines (usually red) |
| toolDiffContext | diff context lines (keep subtle) |
| bashMode | Prompt color in bash mode |
HTML Export Colors
If you use /export to export a session as HTML, you can define colors for the exported page in the theme:
Example
"export": {
"pageBg": "#18181e",
"cardBg": "#1e1e24",
"infoBg": "#3c3728"
}
}
If the export configuration is omitted, the exported page automatically derives colors from userMessageBg.
Theme Creation Tips
The following tips will help your custom theme behave consistently across different terminals.
- Dark terminals: Use bright, saturated colors with sufficiently high contrast
- Light terminals: Use deeper, softer colors; contrast can be lowered appropriately
- Color harmony: Reference mature color schemes such as Nord, Gruvbox, and Tokyo Night as a foundation
- Test thoroughlyEnsure proper display across different message types, tool states, Markdown content, and long text wrapping