---
title: UI, themes and keys
description: Set the TUI's reading width, transcript, HUD, statusline, colour theme, leader key and gear hotkeys in venom.yaml.
section: configuration
order: 30
audience: [user]
sources: [cli/src/venom-config.ts, cli/src/keys.ts, cli/src/hud.ts, cli/src/hud-segments.ts, cli/src/theme, cli/src/meter.ts, cli/src/quiet.ts, cli/src/agents-panel.ts, docs/configuration.md]
features: [configuration.ui, configuration.statusline, configuration.keys]
---

Everything under `ui:`, `statusline:` and `keys:` changes only what the terminal shows and how keys work. None of it reaches the model, so changing it never affects the prompt cache.

```yaml
# ~/.venom/config.yaml
ui:
  theme: low-glare
  width: 110
  verbosity: normal
  hud: compact
  clock: time
statusline: [gear, model, spend, cache, context]
keys:
  leader: ctrl+]
```

Most `ui` keys have a slash command that changes the value now and saves it to `~/.venom/config.yaml`, keeping the file's comments. If a project file sets the same key, the project file wins and the command says so.

## ui {#ui}

| Key | Values | Default | Saved by | Meaning |
|---|---|---|---|---|
| `ui.width` | 40+ columns \| `auto` \| `full` | `auto` (100) | `/width`, `ctrl+g w` | the chat's reading width on wide terminals. `VENOM_MAX_WIDTH` wins |
| `ui.verbosity` | `quiet` \| `normal` \| `full` | `quiet` | `/verbose`, `ctrl+g v` | `quiet`: a compact transcript; `normal`: each call and thinking in full; `full`: everything |
| `ui.meter` | `on` \| `off` \| `compact` \| `full` | `compact` | `/meter` | the per-call meter under each turn (model, tokens, cost). `on` means `compact` |
| `ui.agents_panel` | `on` \| `off` \| `auto` | `auto` | `/agents-panel`, `ctrl+g a` | the panel listing the session's agents and subagents |
| `ui.theme` | theme name \| `auto` | `auto` | `/theme`, `ctrl+g t` | the colour theme ([Themes](#themes)) |
| `ui.theme_overrides` | map token → `#rrggbb` | none | | single colours over the active theme |
| `ui.hud` | `auto` \| `compact` \| `full` \| `custom` | `auto` | `/hud`, `ctrl+g h` | the status bar under the editor. `auto` is `full` on a terminal of 24+ rows and 60+ columns, else `compact` |
| `ui.hud_lines` | list of lists of segment ids | the full layout | | the lines of the `custom` HUD |
| `ui.hud_thresholds` | `{ warn, crit }` percent | `{ warn: 50, crit: 80 }` | | green below `warn`, amber from it, red from `crit` |
| `ui.clock` | `full` \| `time` \| `date` \| `off` | `full` | | the HUD's lower-right corner: date and time, time zone and place; `off` hides it |
| `ui.clock_format` | `12h` \| `24h` | the locale's | | |
| `ui.location` | string | the city of the system time zone | | derived offline (`Asia/Singapore` → Singapore), never looked up |
| `ui.pr_pane` | `{ side, width, auto_refresh }` | | `/prs left\|right` | the pull requests pane (`/prs`, `ctrl+g p`) |
| `ui.pr_pane.side` | `right` \| `left` | `right` | | |
| `ui.pr_pane.width` | columns \| `"45%"` | half the terminal, 44–120 | | in the right margin it takes the margin |
| `ui.pr_pane.auto_refresh` | `true` \| `false` \| seconds | `true` (every 60 s) | | nothing is fetched while the pane is closed |

HUD segment ids for `ui.hud_lines`: `ctx`, `day`, `month`, `in`, `out`, `cache`, `gear`, `model`, `thinking`, `elapsed`, `cost`, `cwd`, `branch`, `risk`, `lease`, `who`, `mode`, `shells`, `agents`, `hints`, `clock`, `tz`, `location`, or a plugin's. A line's trailing `who`, `clock`, `tz` and `location` sit at its right edge.

```yaml
ui:
  hud: custom
  hud_lines:
    - [ctx, day, month]
    - [gear, model, thinking, elapsed, cost]
    - [cwd, branch, mode, agents, clock]
```

## statusline {#statusline}

`statusline:` adds one line under the HUD, in either layout, with the widgets you list in your order. Unset, there is no extra line.

```yaml
statusline: [gear, roles, last, spend, cache, context]
```

```text
⚙ G2 normal · roles fast gpt-5.4-nano · smart gpt-5.5 · last gpt-5.4-mini · today $1.9 19% · cache 90% · ctx 42%
```

| Widget | Shows |
|---|---|
| `gear` | the engaged gear |
| `roles` | the gear's per-role models |
| `model` | the main model |
| `last` | the model that answered the last turn |
| `thinking` | the thinking level |
| `spend` | today's spend from the orchestrator's `/v1/usage`, with the share of the key's daily budget |
| `month` | this month's spend |
| `cost` | this session's cost |
| `cache` | this session's cache hit rate |
| `context` | the share of the context window in use |
| `tokens` | tokens used |
| `mode` | the permission mode |
| `agents` | running agents |

Each widget is a label and a value, so colour is never the only signal. `spend` and `context` are coloured with `ui.hud_thresholds`. A widget with nothing to show yet is left out (`spend` until `/v1/usage` answers, polled at most once a minute; `roles` with no gear engaged). On a narrow terminal the last widgets drop first.

## Themes {#themes}

```bash
venom theme list                 # every theme, where it comes from, the one in use
venom theme preview --all        # each theme drawn
venom theme show amber-night     # its palette and contrast ratios
venom theme tokens               # the tokens ui.theme_overrides accepts
```

In the TUI, `/theme` opens a picker that recolours the screen as you move; Enter saves the theme as `ui.theme`, Esc restores the old one. `/theme <name>`, `/theme next` (also `ctrl+g t`) and `/theme auto` switch and save at once.

| Dark themes | Light themes |
|---|---|
| `venom-night` (default), `venom-dusk`, `amber-night`, `high-contrast`, `colorblind`, `venom-classic`, `low-glare`, `deep-sea`, `forest-night`, `obsidian` | `venom-light`, `sepia-paper`, `daylight`, `high-contrast-light`, `colorblind-light`, `sage-light` |

`auto` picks `venom-night` on a dark terminal and `venom-light` on a light one (the terminal is asked for its background; one that doesn't answer is judged by `COLORFGBG`, else dark). For long or late sessions try `low-glare`, `amber-night` (no blue) or `sepia-paper`; for low vision `high-contrast` or `high-contrast-light`; for a red-green colour deficiency `colorblind` or `colorblind-light`. Every theme keeps text at 4.5:1 contrast or more. `NO_COLOR` turns colour off.

Tweak single tokens over a theme:

```yaml
ui:
  theme: venom-dusk
  theme_overrides:
    accent: "#7aa2f7"
    role.code: "#9ece6a"
```

Venom's own tokens include `bg`, `badge.fg`, `level.ok`, `level.warn`, `level.crit`, `role.*` (agent badges), `mode.*` (permission modes), `hud.path`, `hud.branch`, `hud.model`, `hud.label`, `leader`, `logo.*`, `chart.1` … `chart.6` and `color.*`; pi's tokens (`text`, `muted`, `dim`, `accent`, `success`, `error`, `warning`, `md*`, `syntax*`, …) colour the rest.

Write your own theme as a YAML file in `~/.venom/themes/` (yours) or `.venom/themes/` (the project's):

```bash
venom theme new my-theme                       # ~/.venom/themes/my-theme.yaml from venom-night
venom theme new team --base sepia --project    # .venom/themes/team.yaml
venom theme check ~/.venom/themes/my-theme.yaml
```

```yaml
name: my-theme
base: venom-night
appearance: dark
palette:
  bg: "#1a1b20"
  accent: "#7aa2f7"
tokens:
  hud.model: accent
```

Themes are data, so a project's themes load without trust, but they are validated strictly (known keys, `#rrggbb` colours, contrast floors) and a project theme cannot take a name you already have. Plugins can ship themes too.

## Keys {#keys}

### The leader key {#leader}

Press the leader (`ctrl+g` by default), release it, then press one key. The HUD shows `⌃G …` while it waits; Esc cancels, and it gives up after `keys.leader_timeout_ms`. Pressing the leader twice sends the leader key itself (`ctrl+g ctrl+g` opens pi's external editor).

| After the leader | Does |
|---|---|
| `1` … `9` | shift to the gear on that key |
| `up`, `+`, `=` / `down`, `-` | shift up / down a gear |
| `g` | pick a gear from a list |
| `m` | cycle the permission mode |
| `M` | toggle multiple-subagents mode (`/subagents toggle`) |
| `s` | toggle sudo |
| `a` | show or hide the agents panel |
| `b` | the board (`/board`) |
| `o` | the session's agents (`/ps`) |
| `w` | toggle the reading width between full and auto |
| `W` | list workspaces (`/workspace list`) |
| `u` | push the current workspace (`/workspace push`) |
| `v` | cycle the transcript verbosity |
| `t` | the next theme |
| `c` | copy the last response |
| `n` | mute or unmute sounds (`/sounds toggle`) |
| `x` | clear attachments |
| `h` | switch the HUD between compact and full |
| `?` | a cheat sheet of every binding, plugins' included |

Plugins add their own bindings when the key is free: the bundled ones add `p` (the pull requests pane) and `r` (voice input).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `keys.leader` | key name | `ctrl+g` | the leader. `ctrl+]` and `ctrl+\` are also free in most terminals |
| `keys.leader_timeout_ms` | integer ms | `1500` | how long it waits for the next key |
| `keys.leader_bindings` | map key → action | the table above | change or add bindings; `null` removes one |
| `keys.gear_hotkeys` | boolean | `true` | shift+F1…F12, alt+1…9, alt+. and alt+, for gears |

An action is `gear <n>`, `gear up`, `gear down`, `gear pick`, `mode`, `sudo`, `panel`, `width`, `verbose`, `theme`, `copy`, `help`, `none`, or any slash command:

```yaml
keys:
  leader: ctrl+]
  leader_timeout_ms: 2000
  leader_bindings:
    x: "/export md"
    "0": gear 10
    s: null
```

`ctrl+g` was chosen because it reaches the program unchanged in every terminal and through tmux, whose prefix is `ctrl+b`. Keys are read the way pi reads them, so the kitty keyboard protocol and tmux's `extended-keys` work.

### Gear hotkeys {#gear-hotkeys}

Where the terminal sends them, shift+F*n* and `alt+<n>` shift to gear *n*, and `alt+.` / `alt+,` shift up and down. On macOS, alt shortcuts need the Option key set to send Meta (Terminal.app: Use Option as Meta key; iTerm2: Left Option key Esc+; Ghostty: `macos-option-as-alt = true`). Terminal.app delivers only shift+F5…F12. rxvt and the Linux console don't send shift+F keys distinctly; use the leader there. See [Gears](/docs/configuration/gears.md#shift).

## Troubleshooting

| Symptom | Cause and fix |
|---|---|
| Colours look washed out | Set the terminal's background close to the theme's `bg` (`venom theme show <name>` names it); themes don't paint the terminal background |
| `/theme` says a project file wins | The repository's `venom.yaml` sets `ui.theme`; remove it there or accept the project's choice |
| A project theme is not listed | It failed validation or reuses a name you have; `venom theme list` prints the problem |
| The leader does nothing | Another program took `ctrl+g`; set `keys.leader` to another key |

## Related

- [venom.yaml reference](/docs/configuration/venom-yaml.md#ui).
- [Gears](/docs/configuration/gears.md).
