Skip to content
Docs menu

The terminal UI

What the venom TUI shows and how to change it, from the HUD, call meter, transcript verbosity and reading width to the agents panel, pull requests pane, attachments, sounds and colour themes.

View .md

Running venom in a terminal opens the TUI: a header, the transcript, the editor and the HUD (the status bar) at the bottom. Every display setting below is a preference: the command that changes it saves it, and the next session starts with it. None of it enters the model's context, so changing the display never changes what the model is sent or breaks its prompt cache.

/hud full          the multi-line status bar
/meter full        one line per model call under each turn
/verbose normal    every tool call, thinking in full
/width 120         a wider reading column
/theme             pick a colour theme with a live preview

The startup header shows the venom version, the model and permission mode, the working directory and a one-line summary of what loaded (context files, skills, commands, the leader key). ctrl+o expands it to every key hint and the full lists of context files, skills and prompt templates. quietStartup: true in ~/.venom/agent/settings.json hides it; --verbose shows it anyway.

The HUD

The HUD is the status bar: context use, spend today and this month, tokens in and out, cache, model, gear, permission mode, thinking level, elapsed time, session cost, directory, git branch, risk tier, leases, running shells and agents, and a clock. Each field has a text label and its own colour, so colour is never the only signal; on a narrow terminal the lowest-priority fields go first.

Layout What it is
auto (default) full on a terminal of at least 24 rows and 60 columns, else compact.
compact One line.
full Several lines (holds down to 12 rows and 40 columns).
custom Your own lines of fields, from ui.hud_lines in venom.yaml.

/hud with no argument switches between compact and full; /hud compact|full|auto|custom picks one; ctrl+g h is the leader binding. The choice is saved as ui.hud. The context gauge turns to warning and critical colours at the thresholds in ui.hud_thresholds. Colour follows the theme: NO_COLOR turns it off, FORCE_COLOR forces a level, a 16-colour terminal gets a basic palette.

The call meter

After each turn, the meter adds one dim line per model call made during it: the agent's own, each subagent's, and venom's side requests (the auto-mode classifier, image descriptions, compaction summaries, prompt hooks, /btw), each with the model that answered, tokens, cost and time:

▸ gpt-5.4-mini · 12k↑ 9.8k⚡ 312↓ · $0.003 · 1.8s
▸ explorer gpt-5.4-nano · 3.1k↑ 120↓ · $0.0004 · 0.9s
▸ escalated to smart: tests failed · worker · +$0.042 · passed

/meter on|off|compact|full sets it (default compact; no argument switches it on or off). With off the calls are still counted, so the HUD's session total stays right.

Transcript verbosity

Level What a turn shows
quiet (default) Each run of tool calls as one line (● Read 4 files, ran 3 shell commands), failures under it, each edited file as a diffstat line, each stretch of thinking as its title.
normal Every tool call the way pi draws it, and thinking in full.
full Everything expanded.

/verbose quiet|normal|full sets it; /verbose alone (or ctrl+g v) cycles. A click on a group's line expands it; ctrl+o expands everything for a moment. The final answer, errors and permission prompts always show in full.

Reading width

On a wide terminal the transcript and the editor sit in a left-aligned column of at most 100 columns, so prose keeps a readable line length; the HUD stays full width and the agents panel moves into the margin. /width 120 sets the column, /width auto goes back to 100, /width full uses the whole terminal; ctrl+g w switches between the cap and full. VENOM_MAX_WIDTH (columns, auto or full) wins over the saved setting.

Agents and subagents

The main agent delegates with the task tool: each subagent starts with an empty context, does one job and reports back. venom ships the explorer, worker and verifier agents; your own and a project's agents load beside them (/agents lists them). Per-agent settings go under agents in venom.yaml:

agents:
  explorer:
    model: fast        # a tier (fast, smart, inherit), an alias or a model id
  verifier:
    model: smart

The agents panel is a column on the right listing the session's agents as a tree, each with its role, model, status, how long it has run and what it is doing now.

Command or key What it does
alt+a, ctrl+g a Show or hide the panel.
/agents-panel on|off|auto Keep it on, off, or show it while subagents run and the terminal has room (auto, default); saved as ui.agents_panel.
/agents-panel legend What the glyphs and colours mean.
/ps, ctrl+g o A table of the session's agents: state, wait reason, turns, tools, tokens, cost.
/top The same, sorted by token rate since the last /top.
/subagents on|off|toggle, ctrl+g M Multiple subagents mode. Off, the agent works alone and the task tool refuses; the HUD shows multi off.
/agents The agents the task tool can start.

The pull requests pane

The bundled pull requests plugin shows your open pull requests beside the chat, through the gh CLI (signed in with gh auth login). /prs or ctrl+g p shows or hides it; /prs left and /prs right pick the side. Its side, width and refresh are saved under ui.pr_pane.

Attachments

ctrl+v pastes an image from the clipboard as [Image #1]; pasting or dropping file paths turns images into [Image #n] chips and other files into @path mentions the agent reads. A chip moves and deletes as one unit; delete it to leave the image out. ctrl+g x clears every attachment of the prompt you are writing. A model without image input gets each image described by the vision model (VENOM_VISION_MODEL).

Sounds

venom plays a sound when the main agent finishes, a subagent finishes, a permission prompt waits or a run fails, by default only while the terminal is unfocused. Sounds play in the TUI only, never in print mode, venom serve or ACP.

Command What it does
/sounds List the sounds; pick one to preview, or mute.
/sounds play <name|path|event> Play one.
/sounds mute|unmute|toggle, ctrl+g n For this session.
venom sounds list [--play <name|path>] The same list from the shell, with the configuration and the player venom found.

The built-in sounds are synthesized: chime (main agent done), done, tick (subagent done), pop (step done, off by default), bell, hiss, success, failure (run failed), attention (permission needed) and marimba. Any audio file path works as a custom sound. Which event plays what, the volume, quiet hours and the focus rule are the sounds keys in venom.yaml; VENOM_SOUND_PLAYER sets your own player (mpv --no-video). Hooks can play sounds too.

Themes

Sixteen built-in colour themes, ten dark and six light: venom-night (the dark default), venom-dusk, amber-night, high-contrast, colorblind, venom-classic, low-glare, deep-sea, forest-night, obsidian, venom-light (the light default), sepia-paper, daylight, high-contrast-light, colorblind-light and sage-light. The default setting, auto, picks venom-night or venom-light from the terminal's background.

Command What it does
/theme Pick a theme with a live preview.
/theme <name>, /theme next, /theme auto Set one, take the next (ctrl+g t), or follow the terminal. Saved as ui.theme.
venom theme list The themes, where each comes from, the one in use.
venom theme show <name> Its colours and their WCAG contrast ratios.
venom theme preview [name] [--all] A sample of the HUD, agents panel, meter and /usage in it.
venom theme tokens Every token a theme or ui.theme_overrides can set.
venom theme new <name> [--base <theme>] [--light|--dark] [--project] Write a commented starter theme to ~/.venom/themes/<name>.yaml (.venom/themes/ with --project); never overwrites.
venom theme check <file> Validate a theme file, with its contrast ratios.
venom theme schema The theme file's JSON Schema.

Themes are data, not code, so a project's themes in .venom/themes/ load without trusting the project. Plugins can ship themes too.

Troubleshooting

Symptom Fix
Old frames pile up in the scrollback venom drops the full-screen clear that iTerm2, Terminal.app and PuTTY copy into the scrollback. If you still see it, try --tui-mode regular.
No colours NO_COLOR is set, or TERM=dumb. FORCE_COLOR=3 forces truecolor.
No sounds Muted (/sounds), sounds.enabled: false, the terminal is focused, or no player was found (venom sounds list names the player).
The PR pane is empty gh isn't installed or signed in.