<!-- Markdown mirror. Canonical: https://empryo.com/docs/tools/themes -->

# Themes

> Switch between 44 builtin terminal themes with live preview, or build custom JSON themes that hot-reload as you edit, plus transparency and opacity controls.

## Quick start

Press `/theme` or `Ctrl+K` → search "theme" to open the theme picker. Themes preview live as you navigate.

## Default: `proxysoul-undertow`

Out of the box Empryo wears ProxySoul Undertow on every surface. Pick `system` to follow the OS appearance instead, it resolves to `proxysoul-undertow` on a dark system and `proxysoul-undertow-light` on a light one, across every surface (TUI and desktop). Appearance is detected from the terminal's actual background (OSC 11 query, `COLORFGBG`) first, then the OS preference (macOS appearance, Windows app theme, GNOME color-scheme). Force it with `EMPRYO_APPEARANCE=dark` or `EMPRYO_APPEARANCE=light`. Picking any concrete theme opts out.

## Builtin themes

### Dark

| Theme | Description |
|-------|-------------|
| `proxysoul-undertow` | ProxySoul Undertow, monochrome night tide, sea-glass & dusty rose (the default) |
| `proxysoul-main` | ProxySoul, deep violet night with a hot-pink pulse |
| `proxysoul-coffee` | ProxySoul Coffee, warm umber, amber & burnt orange |
| `proxysoul-water` | ProxySoul Water, blue-black, cyan & teal |
| `proxysoul-crimson` | ProxySoul Crimson, plum-black lit by a crimson glow |
| `proxysoul-empryo` | Empryo brand theme (formerly `proxy-empryo`, the old id still works) |
| `solarized-dark` | Ethan Schoonover's classic |
| `catppuccin` | Catppuccin Mocha |
| `catppuccin-frappe` | Catppuccin Frappe |
| `catppuccin-macchiato` | Catppuccin Macchiato |
| `gruvbox-dark` | Retro groove |
| `tokyo-night` | Tokyo Night |
| `tokyonight-storm` | Tokyo Night Storm |
| `dracula` | Dracula |
| `nord` | Arctic, north-bluish |
| `one-dark` | Atom One Dark |
| `rose-pine` | All natural pine |
| `kanagawa` | Inspired by Katsushika Hokusai |
| `github-dark` | GitHub Dark |
| `everforest-dark` | Comfortable green |
| `ayu-dark` | Ayu Dark |
| `nightfox` | Nightfox |
| `cyberdream` | Cyberdream |
| `oxocarbon` | Oxocarbon |
| `sonokai` | Sonokai |
| `moonfly` | Moonfly |
| `melange` | Melange |
| `solarized-osaka` | Solarized Osaka |
| `bamboo` | Bamboo |
| `nordic` | Nordic |
| `synthwave` | Synthwave |
| `iceberg` | Iceberg |
| `ember` | Ember |
| `vesper` | Vesper |

### Light

| Theme | Description |
|-------|-------------|
| `proxysoul-undertow-light` | Undertow Light, overcast noon tide: slate, sea-glass & rose (`system` on a light OS) |
| `proxysoul-main-light` | ProxySoul Light, lilac paper with violet & pink ink |
| `proxysoul-coffee-light` | Coffee Light, cream paper, espresso & amber ink |
| `proxysoul-water-light` | Water Light, sea-fog paper, deep teal ink |
| `proxysoul-crimson-light` | Crimson Light, blush paper lit by a wine-red glow |
| `proxysoul-empryo-light` | Empryo Light, paper white, forest-green ink |
| `catppuccin-latte` | Catppuccin Latte |
| `one-light` | Atom One Light |
| `github-light` | GitHub Light |

The retired ids `dark`, `light`, `pastel-dusk` and `pastel-dawn` still resolve, to the Undertow pair, so a saved config keeps working.

## Config

Theme is saved globally in `~/.empryo/config.json`:

```json
{
  "theme": {
    "name": "catppuccin",
    "transparent": true,
    "userMessageOpacity": 70,
    "diffOpacity": 30,
    "borderStrength": "strong"
  }
}
```

| Field | Description |
|-------|-------------|
| `name` | Theme ID (builtin or custom) |
| `transparent` | Make background transparent (terminal background bleed-through) |
| `userMessageOpacity` | User message background opacity when transparent: `0` (clear), `30` (dim), `70` (subtle), `100` (solid) |
| `diffOpacity` | Diff background opacity when transparent: `0` (clear), `30` (dim), `70` (subtle), `100` (solid) |
| `borderStrength` | Border visibility: `"default"`, `"strong"`, or `"op"` |

### Theme picker controls

| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate themes (live preview) |
| `Enter` | Apply selected theme |
| `Tab` | Toggle transparent mode |
| `M` | Cycle message background opacity |
| `D` | Cycle diff background opacity |
| `B` | Cycle border strength |

## Custom themes

Create your own theme by adding a JSON file to `~/.empryo/themes/`:

```bash
mkdir -p ~/.empryo/themes
```

### Example

`~/.empryo/themes/my-theme.json`:

```json
{
  "_extends": "dark",
  "_label": "My Theme",
  "_description": "A custom dark theme",
  "_variant": "dark",
  "brand": "#ff6600",
  "brand-secondary": "#ff0040",
  "bg-primary": "#1a1a2e",
  "bg-elevated": "#16213e",
  "text-primary": "#e0e0e0",
  "success": "#00ff88",
  "error": "#ff4444"
}
```

The file name (minus `.json`) becomes the theme ID.

### Metadata fields

| Field | Description |
|-------|-------------|
| `_extends` | Inherit from a builtin theme (default: `dark`, i.e. `proxysoul-undertow`). Only override the tokens you want to change. |
| `_label` | Display name in the theme picker |
| `_description` | Description shown in the picker |
| `_variant` | `"dark"` or `"light"` - controls the indicator in the picker |

### Token reference

Tokens use kebab-case in JSON files (auto-converted to camelCase internally):

- **Brand**: `brand`, `brand-secondary`, `brand-dim`, `brand-alt`
- **Text**: `text-primary`, `text-secondary`, `text-muted`, `text-dim`, `text-faint`, `text-subtle`
- **Backgrounds**: `bg-app`, `bg-primary`, `bg-secondary`, `bg-elevated`, `bg-popup`, `bg-popup-highlight`, `bg-overlay`, `bg-input`, `bg-banner`, `bg-banner-error`, `bg-user`
- **Borders**: `border`, `border-focused`, `border-active`, `border-slash`
- **Status**: `success`, `error`, `warning`, `info`, `amber`
- **Diff**: `diff-added-bg`, `diff-removed-bg`, `diff-added-sign`, `diff-removed-sign`
- **Accents**: `accent-user`, `accent-assistant`, `accent-system`

### Legacy format

You can also define multiple themes in `~/.empryo/themes.json`:

```json
{
  "my-theme": {
    "_extends": "dark",
    "brand": "#ff6600"
  },
  "another-theme": {
    "_extends": "light",
    "brand": "#0066ff"
  }
}
```

## Hot reload

Theme files are watched for changes. Edit a custom theme file and the UI updates instantly - no restart needed.