---
title: The terminal UI
description: 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.
section: cli
order: 40
audience: [user]
sources: [cli/src/hud.ts, cli/src/hud-segments.ts, cli/src/meter.ts, cli/src/quiet.ts, cli/src/reading-width.ts, cli/src/agents-panel.ts, cli/src/tui.ts, cli/src/sounds.ts, cli/src/themes.ts, cli/src/branding.ts, plugins/github-prs/src/index.ts, packages/harness/src/extensions/subagents.ts, packages/harness/src/extensions/attach.ts]
features: [cli.hud, cli.meter, cli.quiet, cli.width, cli.ps, cli.prs, cli.subagents]
---

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.

```text
/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 header {#header}

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 {#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 {#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:

```text
▸ 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 {#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 {#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 {#agents-panel}

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:

```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 {#prs}

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 {#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 {#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 {#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 {#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. |
