pi can create themes. Ask it to build one for your setup.
Themes are JSON files that define colors for the TUI.
- Locations
- Use Your Terminal's Colors
- Selecting a Theme
- Creating a Custom Theme
- Theme Format
- Color Tokens
- Color Values
- Tips
Pi loads themes from:
- Built-in:
system,dark,light,grok-day,grok-night - Global:
~/.senpi/agent/themes/*.json - Project:
.senpi/themes/*.json(only after the project is trusted) - Packages:
themes/directories orpi.themesentries inpackage.json - Settings:
themesarray with files or directories - CLI:
--theme <path>(repeatable)
Disable discovery with --no-themes.
The system theme is the default. It builds senpi's colors from your terminal's own palette, so senpi matches the terminal instead of bringing its own colors:
- senpi queries the terminal's default foreground and background colors and its 16 ANSI colors.
- Each color takes its hue from one ANSI color, for example errors from red and links from blue.
- Each color's lightness is set so it stands out from the background by a minimum contrast. Body text keeps at least a 4.5:1 WCAG contrast ratio on the background and every panel.
- When the terminal switches between light and dark, senpi queries the colors again and rebuilds the theme.
The theme adapts to what the terminal reports:
| Terminal reports | Result |
|---|---|
| Background and ANSI colors | Colors from the terminal palette, placed for the actual background. |
| Background only | senpi's own hues, placed for the actual background. |
| Nothing | ANSI color indices and the terminal's default colors, which the terminal renders itself. Secondary text is faint, and panels have no background color. |
senpi asks the terminal for its colors at startup and waits at most 100 ms before showing the startup header. If the answer arrives later, for example over a slow SSH connection, the colors are applied when it lands. system is a reserved name: a custom theme with that name is ignored.
Select a theme via /settings or in settings.json:
{
"theme": "my-theme"
}Without a theme setting, senpi uses system. To decide whether the terminal is light or dark, senpi reads the reported background color first, then the terminal's light/dark notification, then the COLORFGBG environment variable, and falls back to dark. The same decision picks the theme of a light/dark pair and the appearance of system.
Start an interactive run with a theme without changing the saved setting:
pi --use-theme lightTo follow terminal appearance, use lightTheme/darkTheme syntax:
pi --use-theme light/darkThe CLI value is the initial theme for that run. Choosing another theme later in /settings applies it immediately
and saves it normally.
- Create a theme file:
mkdir -p ~/.senpi/agent/themes
vim ~/.senpi/agent/themes/my-theme.json- Define the theme with all required colors (see Color Tokens):
{
"$schema": "https://raw.githubusercontent.com/earendil-works/pi/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",
"scrollbarTrack": "secondary",
"scrollbarThumb": "",
"searchMatchBg": "#2d2d30",
"searchMatchText": "",
"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",
"thinkingMax": "#ff0088",
"bashMode": "#ffaa00"
}
}- Select the theme via
/settings.
Hot reload: When you edit the currently active custom theme file, pi reloads it automatically for immediate visual feedback.
{
"$schema": "https://raw.githubusercontent.com/earendil-works/pi/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": "",
...
}
}nameis required, must be unique, and must not contain/.appearanceis optional:"dark"or"light", the background the theme is designed for. When omitted, senpi detects it from the theme colors.varsis optional. Define reusable colors here, then reference them incolors.colorsmust define all 51 required tokens.thinkingMax,scrollbarTrack,scrollbarThumb, and the two search highlight tokens are optional and use the fallbacks listed below. The three markdown emphasis tokens are optional and have no fallback.
The $schema field enables editor auto-completion and validation.
Every theme must define all 51 required color tokens. The optional tokens preserve compatibility with existing themes: thinkingMax falls back to thinkingXhigh, scrollbarTrack falls back to muted, scrollbarThumb falls back to text, searchMatchBg falls back to selectedBg, and searchMatchText falls back to text. Other search matches use searchMatchText on searchMatchBg with an underline; the current match reverses that foreground/background pair and uses bold text.
| Token | Purpose |
|---|---|
accent |
Primary accent (logo, selected items, cursor) |
border |
Normal borders |
borderAccent |
Highlighted borders |
borderMuted |
Subtle borders (editor) |
success |
Success states |
error |
Error states |
warning |
Warning states |
muted |
Secondary text |
dim |
Tertiary text |
text |
Default text (usually "") |
thinkingText |
Thinking block text |
scrollbarTrack |
Fullscreen scrollbar track foreground; optional, falls back to muted |
scrollbarThumb |
Fullscreen scrollbar thumb foreground, shared by normal and expanded states; optional, falls back to text |
| Token | Purpose |
|---|---|
selectedBg |
Selected line background |
searchMatchBg |
Transcript search match background and current-match text; optional, falls back to selectedBg |
searchMatchText |
Transcript search match text and current-match background; optional, falls back to text |
userMessageBg |
User message background |
userMessageText |
User message text |
customMessageBg |
Extension message background |
customMessageText |
Extension message text |
customMessageLabel |
Extension message label |
toolPendingBg |
Tool box (pending) |
toolSuccessBg |
Tool box (success) |
toolErrorBg |
Tool box (error) |
toolTitle |
Tool title |
toolOutput |
Tool output text |
| 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 |
mdBold |
**Bold** text; optional |
mdItalic |
*Italic* text; optional |
mdStrikethrough |
~~Strikethrough~~ text; optional |
The emphasis tokens color inline text on top of its bold, italic, or strikethrough style, and take precedence over the surrounding color everywhere markdown renders: headings, blockquotes, thinking blocks, and user and custom messages. When a token is omitted, that text keeps the color of its surroundings, such as a paragraph, heading, or blockquote.
| Token | Purpose |
|---|---|
toolDiffAdded |
Added lines |
toolDiffRemoved |
Removed lines |
toolDiffContext |
Context lines |
| Token | Purpose |
|---|---|
syntaxComment |
Comments |
syntaxKeyword |
Keywords |
syntaxFunction |
Function names |
syntaxVariable |
Variables |
syntaxString |
Strings |
syntaxNumber |
Numbers |
syntaxType |
Types |
syntaxOperator |
Operators |
syntaxPunctuation |
Punctuation |
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 |
thinkingMax |
Maximum thinking; optional, falls back to thinkingXhigh |
| Token | Purpose |
|---|---|
bashMode |
Editor border in bash mode (! prefix) |
The export section controls colors for /export HTML output. If omitted, colors are derived from userMessageBg.
{
"export": {
"pageBg": "#18181e",
"cardBg": "#1e1e24",
"infoBg": "#3c3728"
}
}Six formats are supported:
| Format | Example | Description |
|---|---|---|
| Hex | "#f00" or "#ff0000" |
3- or 6-digit hex RGB |
| OKLCH | "oklch(62% 0.1 200)" |
Perceptual lightness, chroma, and hue |
| OKHSL | "okhsl(250 60% 55%)" |
Hue, saturation, and lightness. Saturation is relative to the most the sRGB gamut allows at that hue and lightness, so every value is in gamut |
| 256-color | 39 |
xterm 256-color palette index (0-255) |
| Variable | "primary" |
Reference to a vars entry |
| Default | "" |
Terminal's default color |
0-15: Basic ANSI colors (terminal-dependent)16-231: 6×6×6 RGB cube (16 + 36×R + 6×G + Bwhere R,G,B are 0-5)232-255: Grayscale ramp
Pi uses 24-bit RGB colors. Most modern terminals support this (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). For older terminals with only 256-color support, pi falls back to the nearest approximation. OKLCH values are gamut-mapped to sRGB, and HTML exports convert OKHSL values to hex because CSS does not support them. Terminals with TERM=*-direct are detected as truecolor.
Check truecolor support:
echo $COLORTERM # Should output "truecolor" or "24bit"Dark terminals: Use bright, saturated colors with higher contrast.
Light terminals: Use darker, muted colors with lower contrast.
Color harmony: Start with a base palette (Nord, Gruvbox, Tokyo Night), define it in vars, and reference consistently.
Testing: Check your theme with different message types, tool states, markdown content, and long wrapped text.
VS Code: Set terminal.integrated.minimumContrastRatio to 1 for accurate colors.
See the built-in themes: