mirror of https://github.com/badlogic/pi-mono.git synced 2026-11-05 23:37:25 +00:00

feat(tui,coding-agent): add color values and theme styling (#8398 )

Expose theme colors as values and add theme.style() for combined styling.

- @earendil-works/pi-tui gains a Color type (palette index, sRGB, OKLCH) with parseColor(), mixColors(), colorToHex(), colorToRgb(), styleText() and related helpers.
- Theme JSON accepts #rgb and oklch(...) values and an optional appearance ("dark" or "light"), detected from the theme colors when omitted.
- theme.style() combines tokens or concrete colors with text attributes; theme.colors exposes concrete colors, including the terminal's reported default colors (OSC 10/11) for tokens set to "".
- Terminals with TERM=*-direct are detected as truecolor.

2026-09-24 14:42:22 +02:00

5.5 KiB

Raw Blame History

Customize Pi with themes

Themes control the colors Pi uses in interactive mode and HTML exports. Pi includes dark and light themes. You can select one theme, follow your terminal's light or dark appearance, or create your own palette.

Choose a theme

Open /settings and select Theme. You can use one theme for every terminal appearance or choose separate themes for light and dark terminals.

The selection is saved as the theme setting:

{
  "theme": "dark"
}

Automatic mode stores the light theme first and the dark theme second:

{
  "theme": "light/dark"
}

When automatic mode is active, Pi changes themes when the terminal reports an appearance change. Theme names cannot contain / because Pi reserves it for this setting format.

Use --use-theme to choose the initial theme for one invocation without changing the saved setting:

pi --use-theme light
pi --use-theme light/dark

See CLI resources for the command-line option.

Create a custom theme

Copy one of the built-in themes or create a new JSON file conforming to the schema.

Save the file as <agent-dir>/themes/my-theme.json. The agent directory defaults to ~/.pi/agent.
Set its name to my-theme.
Change values in vars and colors.
Select my-theme through /settings.

Use the theme name as the filename. Pi hot-reloads the active user theme only from <agent-dir>/themes/<name>.json. Run /reload after adding or changing a theme from any other source.

Understand the theme file

Property	Required	Responsibility
`$schema`	No	Enables editor validation and completion against Pi's published schema.
`name`	Yes	Identifies the theme in selectors and settings. It must be unique and cannot contain `/`.
`appearance`	No	`"dark"` or `"light"`: the background the theme is designed for. Pi detects it from the theme colors when omitted.
`vars`	No	Defines reusable color values. Variables can reference other variables.
`colors`	Yes	Assigns colors to terminal UI roles. The schema identifies required and optional roles.
`export`	No	Overrides page and panel backgrounds in HTML exports.

A color can be written in five forms:

Form	Example	Meaning
RGB hexadecimal	`"#0af"` or `"#00aaff"`	A three- or six-digit sRGB color.
OKLCH	`"oklch(62% 0.1 200)"`	Perceptual lightness, chroma, and hue.
256-color index	`39`	An ANSI palette index from `0` through `255`.
Variable reference	`"primary"`	The value of an entry in `vars`.
Terminal default	`""`	The terminal's default foreground or background color.

Terminal default colors render as the terminal's own colors. Where Pi needs a concrete value, such as HTML export or extension color math, it uses the default colors the terminal reports, or a black or white guess based on the theme's appearance.

Pi resolves chained variable references. A missing variable or circular reference makes the theme invalid. Pi uses truecolor when available, gamut-maps OKLCH to sRGB, and approximates colors for 256-color terminals. If colors differ from their source values, check your terminal's truecolor detection and contrast settings. See Configure Your Terminal.

Use the theme JSON schema for the exact properties, required colors, and accepted value types.

Pi reports invalid theme files during startup and /reload.

Find the color to change

Theme colors describe interface roles rather than individual components. Use these groups to find the relevant part of the schema:

Area	Color names
General interface	`accent`, `border*`, `text`, `muted`, `dim`, `success`, `error`, `warning`
Selection and fullscreen	`selectedBg`, `searchMatch`, `scrollbar`
Messages	`userMessage`, `customMessage`, `thinkingText`
Tool execution	`toolPendingBg`, `toolSuccessBg`, `toolErrorBg`, `toolTitle`, `toolOutput`
Markdown	`md*`
Tool diffs	`toolDiff*`
Syntax highlighting	`syntax*`
Editor modes	`thinking*`, `bashMode`
HTML export	`export.pageBg`, `export.cardBg`, `export.infoBg`

The schema is the format reference. The built-in themes provide complete values that you can copy and adjust.

Five colors are optional and inherit another color when omitted:

Optional color	Fallback
`scrollbarTrack`	`muted`
`scrollbarThumb`	`text`
`searchMatchBg`	`selectedBg`
`searchMatchText`	`text`
`thinkingMax`	`thinkingXhigh`

If export colors are omitted, Pi derives HTML page and panel backgrounds from userMessageBg.

Load a theme from a project or package

Place a project theme in .pi/themes/. Project themes load only after project trust is granted.

You can also load theme files and directories through the themes setting or distribute them in a Pi package. See Configuration, Settings, and Pi Packages.

Each loaded theme must have a unique name. Pi reports duplicate names as resource collisions.

5.5 KiB Raw Blame History