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

# Themes

> Pick from over 40 built-in color themes with a live preview, follow your system's light or dark mode, or write your own JSON theme that reloads as you edit it.

## Quick start

Run `/theme`, or press `Ctrl+K` and search for "theme", to open the theme picker. The app changes color as you move through the list, so you can see each theme before you choose it.

## Default: `proxysoul-undertow`

Empryo uses the ProxySoul Undertow theme by default, in both the terminal UI and the desktop app.

To follow your system's light or dark mode instead, pick `system`. It uses `proxysoul-undertow` when your system is dark and `proxysoul-undertow-light` when it is light.

To decide between light and dark, Empryo first checks your terminal's background color. If it cannot tell, it uses your operating system's setting (macOS appearance, the Windows app theme, or the GNOME color scheme). To force one, set `EMPRYO_APPEARANCE=dark` or `EMPRYO_APPEARANCE=light`.

Picking any other theme turns off the automatic switching.

## Builtin themes

### Dark

| Theme | Description |
|-------|-------------|
| `proxysoul-undertow` | ProxySoul Undertow: dark blue-grey with sea-glass green and dusty rose (the default) |
| `proxysoul-main` | ProxySoul: deep violet with hot pink |
| `proxysoul-coffee` | ProxySoul Coffee: warm brown, amber and burnt orange |
| `proxysoul-water` | ProxySoul Water: blue-black, cyan and teal |
| `proxysoul-crimson` | ProxySoul Crimson: plum-black with crimson |
| `proxysoul-empryo` | The Empryo brand theme (the old id `proxy-empryo` 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: slate, sea-glass green and rose (what `system` uses on a light system) |
| `proxysoul-main-light` | ProxySoul Light: lilac with violet and pink |
| `proxysoul-coffee-light` | Coffee Light: cream, espresso and amber |
| `proxysoul-water-light` | Water Light: pale grey-blue with deep teal |
| `proxysoul-crimson-light` | Crimson Light: blush with wine red |
| `proxysoul-empryo-light` | Empryo Light: white with forest green |
| `catppuccin-latte` | Catppuccin Latte |
| `one-light` | Atom One Light |
| `github-light` | GitHub Light |

The old theme ids `dark`, `light`, `pastel-dusk` and `pastel-dawn` still work. They now point to the Undertow themes, so an older config does not break.

## Config

Your theme is saved for all projects in `~/.empryo/config.json`:

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

| Field | Description |
|-------|-------------|
| `name` | The theme id (built-in or your own) |
| `transparent` | Make the background transparent, so your terminal's own background shows through |
| `userMessageOpacity` | How solid the background of your messages is in transparent mode: `0` (clear), `30` (dim), `70` (subtle), `100` (solid) |
| `diffOpacity` | How solid the background of diffs is in transparent mode: `0` (clear), `30` (dim), `70` (subtle), `100` (solid) |
| `borderStrength` | How visible borders are: `"default"`, `"strong"` or `"op"` |

### Theme picker controls

These keys work in the terminal UI theme picker:

| Key | Action |
|-----|--------|
| `↑` / `↓` | Move through themes (with live preview) |
| `Enter` | Apply the selected theme |
| `Tab` | Turn transparent mode on or off |
| `M` | Change the message background opacity |
| `D` | Change the diff background opacity |
| `B` | Change the border strength |

## Custom themes

To make your own theme, add 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 without `.json` becomes the theme id. This one is `my-theme`.

### Metadata fields

| Field | Description |
|-------|-------------|
| `_extends` | The built-in theme to start from. You only list the colors you want to change. Default: `dark`, which means `proxysoul-undertow` |
| `_label` | The name shown in the theme picker |
| `_description` | The description shown in the picker |
| `_variant` | `"dark"` or `"light"`, shown as an icon in the picker |

### Token reference

Write color names in kebab-case, like `bg-primary`:

- **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 put several themes in one file, `~/.empryo/themes.json`:

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

## Hot reload

Empryo watches your theme files. When you save a change to a custom theme, the app updates right away. You do not need to restart.