Quick start

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

Default: `system`

Out of the box Empryo uses the system theme — it resolves to pastel-dusk on a dark system and pastel-dawn 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
`dark`	Empryo dark
`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
`proxysoul-main`	proxySoul - deep purple with hot pink
`proxysoul-coffee`	proxySoul Coffee - warm amber & burnt orange
`proxysoul-water`	proxySoul Water - ocean blue & teal
`proxy-empryo`	Empryo brand theme
`pastel-dusk`	Soft pastel, dark (`system` default when dark)
`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
`light`	Clean light theme
`catppuccin-latte`	Catppuccin Latte
`one-light`	Atom One Light
`github-light`	GitHub Light
`pastel-dawn`	Soft pastel, light (`system` default when light)

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`). 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.