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:

{
  "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/:

mkdir -p ~/.empryo/themes

Example

~/.empryo/themes/my-theme.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:

{
  "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.