Skip to content
Docs menu

UI, themes and keys

Set the TUI's reading width, transcript, HUD, statusline, colour theme, leader key and gear hotkeys in venom.yaml.

View .md

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.

# ~/.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

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

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

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.

statusline: [gear, roles, last, spend, cache, context]
⚙ 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

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:

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):

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
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

The leader key

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:

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

Where the terminal sends them, shift+Fn 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.

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