UI, themes and keys
Set the TUI's reading width, transcript, HUD, statusline, colour theme, leader key and gear hotkeys in venom.yaml.
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 acceptsIn 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.yamlname: my-theme
base: venom-night
appearance: dark
palette:
bg: "#1a1b20"
accent: "#7aa2f7"
tokens:
hud.model: accentThemes 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: nullctrl+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 |