> omp can create themes. Ask it to build one for your use case.

# OMP Coding Agent Themes

Themes allow you to customize the colors used throughout the coding agent TUI.

## Color Tokens

Every theme must define all color tokens. There are no optional colors.

### Core UI (10 colors)

| Token          | Purpose               | Examples                             |
| -------------- | --------------------- | ------------------------------------ |
| `accent`       | Primary accent color  | Logo, selected items, cursor (›)     |
| `border`       | Normal borders        | Selector borders, horizontal lines   |
| `borderAccent` | Highlighted borders   | Changelog borders, special panels    |
| `borderMuted`  | Subtle borders        | Editor borders, secondary separators |
| `success`      | Success states        | Success messages, diff additions     |
| `error`        | Error states          | Error messages, diff deletions       |
| `warning`      | Warning states        | Warning messages                     |
| `muted`        | Secondary/dimmed text | Metadata, descriptions, output       |
| `dim`          | Very dimmed text      | Less important info, placeholders    |
| `text`         | Default text color    | Main content (usually `""`)          |
| `thinkingText` | Thinking block text   | Assistant reasoning traces           |

### Backgrounds & Content Text (11 colors)

| Token                | Purpose                                                           |
| -------------------- | ----------------------------------------------------------------- |
| `selectedBg`         | Selected/active line background (e.g., tree selector)             |
| `userMessageBg`      | User message background                                           |
| `userMessageText`    | User message text color                                           |
| `customMessageBg`    | Hook custom message background                                    |
| `customMessageText`  | Hook custom message text color                                    |
| `customMessageLabel` | Hook custom message label/type text                               |
| `toolPendingBg`      | Tool execution box (pending state)                                |
| `toolSuccessBg`      | Tool execution box (success state)                                |
| `toolErrorBg`        | Tool execution box (error state)                                  |
| `toolTitle`          | Tool execution title/heading (e.g., `$ command`, `read file.txt`) |
| `toolOutput`         | Tool execution output text                                        |

### Markdown (10 colors)

| Token               | Purpose                       |
| ------------------- | ----------------------------- |
| `mdHeading`         | Heading text (`#`, `##`, etc) |
| `mdLink`            | Link text                     |
| `mdLinkUrl`         | Link URL (in parentheses)     |
| `mdCode`            | Inline code (backticks)       |
| `mdCodeBlock`       | Code block content            |
| `mdCodeBlockBorder` | Code block fences (```)       |
| `mdQuote`           | Blockquote text               |
| `mdQuoteBorder`     | Blockquote border (`│`)       |
| `mdHr`              | Horizontal rule (`---`)       |
| `mdListBullet`      | List bullets/numbers          |

### Tool Diffs (3 colors)

| Token             | Purpose                     |
| ----------------- | --------------------------- |
| `toolDiffAdded`   | Added lines in tool diffs   |
| `toolDiffRemoved` | Removed lines in tool diffs |
| `toolDiffContext` | Context lines in tool diffs |

Note: Diff colors are specific to tool execution boxes and must work with tool background colors.

### Syntax Highlighting (9 colors)

Future-proofing for syntax highlighting support:

| Token               | Purpose                          |
| ------------------- | -------------------------------- |
| `syntaxComment`     | Comments                         |
| `syntaxKeyword`     | Keywords (`if`, `function`, etc) |
| `syntaxFunction`    | Function names                   |
| `syntaxVariable`    | Variable names                   |
| `syntaxString`      | String literals                  |
| `syntaxNumber`      | Number literals                  |
| `syntaxType`        | Type names                       |
| `syntaxOperator`    | Operators (`+`, `-`, etc)        |
| `syntaxPunctuation` | Punctuation (`;`, `,`, etc)      |

### Thinking Level Borders (6 colors)

Editor border colors that indicate the current thinking/reasoning level:

| Token             | Purpose                                                           |
| ----------------- | ----------------------------------------------------------------- |
| `thinkingOff`     | Border when thinking is off (most subtle)                         |
| `thinkingMinimal` | Border for minimal thinking                                       |
| `thinkingLow`     | Border for low thinking                                           |
| `thinkingMedium`  | Border for medium thinking                                        |
| `thinkingHigh`    | Border for high thinking                                          |
| `thinkingXhigh`   | Border for xhigh thinking (most prominent, OpenAI codex-max only) |

These create a visual hierarchy: off → minimal → low → medium → high → xhigh

### Bash Mode (1 color)

| Token      | Purpose                                          |
| ---------- | ------------------------------------------------ |
| `bashMode` | Editor border color when in bash mode (! prefix) |

**Total: 50 color tokens** (all required)

### HTML Export Colors (optional)

The `export` section is optional and controls colors used when exporting sessions to HTML via `/export`. If not specified, these colors are automatically derived from `userMessageBg` based on luminance detection.

| Token    | Purpose                                                       |
| -------- | ------------------------------------------------------------- |
| `pageBg` | Page background color                                         |
| `cardBg` | Card/container background (headers, stats boxes)              |
| `infoBg` | Info sections background (system prompt, notices, compaction) |

Example:

```json
{
	"export": {
		"pageBg": "#18181e",
		"cardBg": "#1e1e24",
		"infoBg": "#3c3728"
	}
}
```

## Theme Format

Themes are defined in JSON files with the following structure:

```json
{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/theme-schema.json",
  "name": "my-theme",
  "vars": {
    "blue": "#0066cc",
    "gray": 242,
    "brightCyan": 51
  },
  "colors": {
    "accent": "blue",
    "muted": "gray",
    "thinkingText": "gray",
    "text": "",
    ...
  }
}
```

## Symbols

Themes can also customize specific UI symbols (icons, separators, bullets, etc.). Use `symbols.preset` to set a theme default (overridden by user settings), and `symbols.overrides` to override individual keys.

Example:

```json
{
	"symbols": {
		"preset": "ascii",
		"overrides": {
			"icon.model": "[M]",
			"sep.powerlineLeft": ">",
			"sep.powerlineRight": "<"
		}
	}
}
```

Symbol keys by category:

- Status: `status.success`, `status.error`, `status.warning`, `status.info`, `status.pending`, `status.disabled`, `status.enabled`, `status.running`, `status.shadowed`, `status.aborted`
- Navigation: `nav.cursor`, `nav.selected`, `nav.expand`, `nav.collapse`, `nav.back`
- Tree: `tree.branch`, `tree.last`, `tree.vertical`, `tree.horizontal`, `tree.hook`
- Boxes (rounded): `boxRound.topLeft`, `boxRound.topRight`, `boxRound.bottomLeft`, `boxRound.bottomRight`, `boxRound.horizontal`, `boxRound.vertical`
- Boxes (sharp): `boxSharp.topLeft`, `boxSharp.topRight`, `boxSharp.bottomLeft`, `boxSharp.bottomRight`, `boxSharp.horizontal`, `boxSharp.vertical`, `boxSharp.cross`, `boxSharp.teeDown`, `boxSharp.teeUp`, `boxSharp.teeRight`, `boxSharp.teeLeft`
- Separators: `sep.powerline`, `sep.powerlineThin`, `sep.powerlineLeft`, `sep.powerlineRight`, `sep.powerlineThinLeft`, `sep.powerlineThinRight`, `sep.dot`, `sep.slash`, `sep.pipe`
- Icons: `icon.model`, `icon.folder`, `icon.file`, `icon.git`, `icon.branch`, `icon.tokens`, `icon.context`, `icon.cost`, `icon.time`, `icon.pi`, `icon.agents`, `icon.cache`, `icon.input`, `icon.output`, `icon.host`, `icon.session`, `icon.package`, `icon.warning`, `icon.rewind`, `icon.auto`, `icon.extensionSkill`, `icon.extensionTool`, `icon.extensionSlashCommand`, `icon.extensionMcp`, `icon.extensionRule`, `icon.extensionHook`, `icon.extensionPrompt`, `icon.extensionContextFile`, `icon.extensionInstruction`
- Thinking: `thinking.minimal`, `thinking.low`, `thinking.medium`, `thinking.high`, `thinking.xhigh`
- Checkboxes: `checkbox.checked`, `checkbox.unchecked`
- Formatting: `format.bullet`, `format.dash`
- Markdown: `md.quoteBorder`, `md.hrChar`, `md.bullet`

### Color Values

Four formats are supported:

1. **Hex colors**: `"#ff0000"` (6-digit hex RGB)
2. **256-color palette**: `39` (number 0-255, xterm 256-color palette)
3. **Color references**: `"blue"` (must be defined in `vars`)
4. **Terminal default**: `""` (empty string, uses terminal's default color)

### The `vars` Section

The optional `vars` section allows you to define reusable colors:

```json
{
	"vars": {
		"nord0": "#2E3440",
		"nord1": "#3B4252",
		"nord8": "#88C0D0",
		"brightBlue": 39
	},
	"colors": {
		"accent": "nord8",
		"muted": "nord1",
		"mdLink": "brightBlue"
	}
}
```

Benefits:

- Reuse colors across multiple tokens
- Easier to maintain theme consistency
- Can reference standard color palettes

Variables can be hex colors (`"#ff0000"`), 256-color indices (`42`), or references to other variables.

### Terminal Default (empty string)

Use `""` (empty string) to inherit the terminal's default foreground/background color:

```json
{
	"colors": {
		"text": "" // Uses terminal's default text color
	}
}
```

This is useful for:

- Main text color (adapts to user's terminal theme)
- Creating themes that blend with terminal appearance

## Built-in Themes

OMP comes with two built-in themes:

### `dark` (default)

Optimized for dark terminal backgrounds with bright, saturated colors.

### `light`

Optimized for light terminal backgrounds with darker, muted colors.

## Selecting a Theme

Themes are configured in the settings (accessible via `/settings`):

```json
{
	"theme": "dark"
}
```

Or use the `/theme` command interactively.

On first run, OMP detects your terminal's background and sets a sensible default (`dark` or `light`).

## Custom Themes

### Theme Locations

Custom themes are loaded from `~/.omp/agent/themes/*.json`.

### Creating a Custom Theme

1. **Create theme directory:**

   ```bash
   mkdir -p ~/.omp/agent/themes
   ```

2. **Create theme file:**

   ```bash
   vim ~/.omp/agent/themes/my-theme.json
   ```

3. **Define all colors:**

   ```json
   {
   	"$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/theme-schema.json",
   	"name": "my-theme",
   	"vars": {
   		"primary": "#00aaff",
   		"secondary": 242,
   		"brightGreen": 46
   	},
   	"colors": {
   		"accent": "primary",
   		"border": "primary",
   		"borderAccent": "#00ffff",
   		"borderMuted": "secondary",
   		"success": "brightGreen",
   		"error": "#ff0000",
   		"warning": "#ffff00",
   		"muted": "secondary",
   		"text": "",

   		"userMessageBg": "#2d2d30",
   		"userMessageText": "",
   		"toolPendingBg": "#1e1e2e",
   		"toolSuccessBg": "#1e2e1e",
   		"toolErrorBg": "#2e1e1e",
   		"toolText": "",

   		"mdHeading": "#ffaa00",
   		"mdLink": "primary",
   		"mdCode": "#00ffff",
   		"mdCodeBlock": "#00ff00",
   		"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"
   	}
   }
   ```

4. **Select your theme:**
   - Use `/settings` command and set `"theme": "my-theme"`
   - Or use `/theme` command interactively

## Tips

### Light vs Dark Themes

**For dark terminals:**

- Use bright, saturated colors
- Higher contrast
- Example: `#00ffff` (bright cyan)

**For light terminals:**

- Use darker, muted colors
- Lower contrast to avoid eye strain
- Example: `#008888` (dark cyan)

### Color Harmony

- Start with a base palette (e.g., Nord, Gruvbox, Tokyo Night)
- Define your palette in `defs`
- Reference colors consistently

### Testing

Test your theme with:

- Different message types (user, assistant, errors)
- Tool executions (success and error states)
- Markdown content (headings, code, lists, etc)
- Long text that wraps

## Color Format Reference

### Hex Colors

Standard 6-digit hex format:

- `"#ff0000"` - Red
- `"#00ff00"` - Green
- `"#0000ff"` - Blue
- `"#808080"` - Gray
- `"#ffffff"` - White
- `"#000000"` - Black

RGB values: `#RRGGBB` where each component is `00-ff` (0-255)

### 256-Color Palette

Use numeric indices (0-255) to reference the xterm 256-color palette:

**Colors 0-15:** Basic ANSI colors (terminal-dependent, may be themed)

- `0` - Black
- `1` - Red
- `2` - Green
- `3` - Yellow
- `4` - Blue
- `5` - Magenta
- `6` - Cyan
- `7` - White
- `8-15` - Bright variants

**Colors 16-231:** 6×6×6 RGB cube (standardized)

- Formula: `16 + 36×R + 6×G + B` where R, G, B are 0-5
- Example: `39` = bright cyan, `196` = bright red

**Colors 232-255:** Grayscale ramp (standardized)

- `232` - Darkest gray
- `255` - Near white

Example usage:

```json
{
	"vars": {
		"gray": 242,
		"brightCyan": 51,
		"darkBlue": 18
	},
	"colors": {
		"muted": "gray",
		"accent": "brightCyan"
	}
}
```

**Benefits:**

- Works everywhere (`TERM=xterm-256color`)
- No truecolor detection needed
- Standardized RGB cube (16-231) looks the same on all terminals

### Terminal Compatibility

OMP uses 24-bit RGB colors (`\x1b[38;2;R;G;Bm`). Most modern terminals support this:

- ✅ iTerm2, Alacritty, Kitty, WezTerm
- ✅ Windows Terminal
- ✅ VS Code integrated terminal
- ✅ Modern GNOME Terminal, Konsole

For older terminals with only 256-color support, OMP automatically falls back to the nearest 256-color approximation.

To check if your terminal supports truecolor:

```bash
echo $COLORTERM  # Should output "truecolor" or "24bit"
```

## Example Themes

See the built-in themes for complete examples:

- [Dark theme](../src/themes/dark.json)
- [Light theme](../src/themes/light.json)

## Schema Validation

Themes are validated on load using [TypeBox](https://github.com/sinclairzx81/typebox) + [Ajv](https://ajv.js.org/).

Invalid themes will show an error with details about what's wrong:

```
Error loading theme 'my-theme':
  - colors.accent: must be string or number
  - colors.mdHeading: required property missing
```

For editor support, the JSON schema is available at:

```
https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/theme-schema.json
```

Add to your theme file for auto-completion and validation:

```json
{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/theme-schema.json",
  ...
}
```

## Implementation

### Theme Class

Themes are loaded and converted to a `Theme` class that provides type-safe color methods:

```typescript
class Theme {
	// Apply foreground color
	fg(color: ThemeColor, text: string): string;

	// Apply background color
	bg(color: ThemeBg, text: string): string;

	// Text attributes (preserve current colors)
	bold(text: string): string;
	italic(text: string): string;
	underline(text: string): string;
}
```

### Global Theme Instance

The active theme is available as a global singleton in `coding-agent`:

```typescript
// theme.ts
export let theme: Theme;

export function setTheme(name: string) {
	theme = loadTheme(name);
}

// Usage throughout coding-agent
import { theme } from "./theme.js";

theme.fg("accent", "Selected");
theme.bg("userMessageBg", content);
```

### TUI Component Theming

TUI components (like `Markdown`, `SelectList`, `Editor`) are in the `@oh-my-pi/pi-tui` package and don't have direct access to the theme. Instead, they define interfaces for the colors they need:

```typescript
// In @oh-my-pi/pi-tui
export interface MarkdownTheme {
	heading: (text: string) => string;
	link: (text: string) => string;
	linkUrl: (text: string) => string;
	code: (text: string) => string;
	codeBlock: (text: string) => string;
	codeBlockBorder: (text: string) => string;
	quote: (text: string) => string;
	quoteBorder: (text: string) => string;
	hr: (text: string) => string;
	listBullet: (text: string) => string;
	bold: (text: string) => string;
	italic: (text: string) => string;
	strikethrough: (text: string) => string;
	underline: (text: string) => string;
}
```

The `coding-agent` provides themed functions when creating components:

```typescript
// In coding-agent
import { theme } from "./theme.js";
import { Markdown } from "@oh-my-pi/pi-tui";

// Helper to create markdown theme functions
function getMarkdownTheme(): MarkdownTheme {
	return {
		heading: (text) => theme.fg("mdHeading", text),
		link: (text) => theme.fg("mdLink", text),
		linkUrl: (text) => theme.fg("mdLinkUrl", text),
		code: (text) => theme.fg("mdCode", text),
		codeBlock: (text) => theme.fg("mdCodeBlock", text),
		codeBlockBorder: (text) => theme.fg("mdCodeBlockBorder", text),
		quote: (text) => theme.fg("mdQuote", text),
		quoteBorder: (text) => theme.fg("mdQuoteBorder", text),
		hr: (text) => theme.fg("mdHr", text),
		listBullet: (text) => theme.fg("mdListBullet", text),
		bold: (text) => theme.bold(text),
		italic: (text) => theme.italic(text),
		underline: (text) => theme.underline(text),
		strikethrough: (text) => chalk.strikethrough(text),
	};
}

// Create markdown with theme
const md = new Markdown(text, 1, 1, getMarkdownTheme(), { bgColor: theme.bg("userMessageBg") });
```

This approach:

- Keeps TUI components theme-agnostic (reusable in other projects)
- Maintains type safety via interfaces
- Allows components to have sensible defaults if no theme provided
- Centralizes theme access in `coding-agent`

**Example usage:**

```typescript
const theme = loadTheme("dark");

// Apply foreground colors
theme.fg("accent", "Selected");
theme.fg("success", "✓ Done");
theme.fg("error", "Failed");

// Apply background colors
theme.bg("userMessageBg", content);
theme.bg("toolSuccessBg", output);

// Combine styles
theme.bold(theme.fg("accent", "Title"));
theme.italic(theme.fg("muted", "metadata"));

// Nested foreground + background
const userMsg = theme.bg("userMessageBg", theme.fg("userMessageText", "Hello"));
```

**Color resolution:**

1. **Detect terminal capabilities:**
   - Check `$COLORTERM` env var (`truecolor` or `24bit` → truecolor support)
   - Check `$TERM` env var (`*-256color` → 256-color support)
   - Fallback to 256-color mode if detection fails

2. **Load JSON theme file**

3. **Resolve `vars` references recursively:**

   ```json
   {
   	"vars": {
   		"primary": "#0066cc",
   		"accent": "primary"
   	},
   	"colors": {
   		"accent": "accent" // → "primary" → "#0066cc"
   	}
   }
   ```

4. **Convert colors to ANSI codes based on terminal capability:**

   **Truecolor mode (24-bit):**
   - Hex (`"#ff0000"`) → `\x1b[38;2;255;0;0m`
   - 256-color (`42`) → `\x1b[38;5;42m` (keep as-is)
   - Empty string (`""`) → `\x1b[39m`

   **256-color mode:**
   - Hex (`"#ff0000"`) → convert to nearest RGB cube color → `\x1b[38;5;196m`
   - 256-color (`42`) → `\x1b[38;5;42m` (keep as-is)
   - Empty string (`""`) → `\x1b[39m`

   **Hex to 256-color conversion:**

   ```typescript
   // Convert RGB to 6x6x6 cube (colors 16-231)
   r_index = Math.round((r / 255) * 5);
   g_index = Math.round((g / 255) * 5);
   b_index = Math.round((b / 255) * 5);
   color_index = 16 + 36 * r_index + 6 * g_index + b_index;
   ```

5. **Cache as `Theme` instance**

This ensures themes work correctly regardless of terminal capabilities, with graceful degradation from truecolor to 256-color.
