Terminal UI (TUI)

docker-agent's default interface is a rich, interactive terminal UI with file attachments, themes, session management, and more.

Launching the TUI

# Launch with a config
$ docker agent run agent.yaml

# Start with an initial message
$ docker agent run agent.yaml "Help me refactor this code"

# Auto-approve all tool calls
$ docker agent run agent.yaml --yolo

# Enable debug logging
$ docker agent run agent.yaml --debug

# Override the application name shown in the status bar and window title
$ docker agent run agent.yaml --app-name "My Project"

# Preselect a color theme
$ docker agent run agent.yaml --theme dracula

# Hide the sidebar (cannot be re-enabled via Ctrl+B)
$ docker agent run agent.yaml --sidebar=false

# Disable specific slash commands
$ docker agent run agent.yaml --disable-commands="/cost,/eval,/model"

# Open in read-only mode to review a past session without sending new messages
$ docker agent run agent.yaml --session -1 --session-read-only

# Use the lean TUI for this run
$ docker agent run agent.yaml --lean

Lean TUI

The lean TUI uses a simplified terminal interface with minimal chrome. To make it the default for interactive runs, set lean in your user config:

# ~/.config/cagent/config.yaml
settings:
  lean: true

Omit lean or set it to false to keep the full TUI as the default. You can still use --lean for a single run, or --lean=false to use the full TUI when settings.lean is enabled.

The lean TUI supports steering: messages submitted while the agent is running are queued and delivered to the active session. Pending steering messages appear with muted styling at the end of the live stream so you can see what will be sent next.

Slash Commands

Type / during a session to see available commands, or press Ctrl+K for the command palette:

Slash commands (both built-in and named) execute immediately when entered. Regular chat messages sent while the agent is working are steered into the ongoing stream by default: the agent picks them up mid-turn (they appear in the transcript at the point the agent sees them) without breaking the stream. Prefer the previous end-of-turn behavior? Switch While agent is working to Queue on the Behavior tab of /settings; queued messages are processed in order once the stream stops.

Agents Panel

The sidebar's Agents section lists every agent in the team. The current agent is shown as a focus card (rendered in place at its position in the list) with its name, a wrapped description, its full provider/model, and a thinking line. Every other agent is shown as a compact two-line row — line 1 is the shortcut/spinner, the agent name (in its accent color), and a right-aligned thinking gauge; line 2 is the indented full provider/model — so a large team stays scannable while still showing each model. Once an agent has run (in the main session, as a delegated sub-agent, or as a background agent task), line 2 also carries its latest context usage as a right-aligned percentage of its context window, so per-agent context accounting is visible at a glance across the whole team. Agents are separated by a blank line so the two-line rows stay visually distinct. The effort gauge is the only visual language for thinking; the focus card and the Agent Inspector spell out the exact level alongside it. Left-click any agent to switch to it.

Agent inspector

Open a read-only Agent Inspector to inspect any agent's full configuration combined with its live state. The instruction/system prompt is deliberately omitted; everything else the agent declares is shown:

• Right-click any agent (card or row) to open the inspector without switching to it.
• Ctrl+left-click any agent does the same — a fallback for terminals that don't forward right-clicks.
• Left-click always switches to the agent.

The title is rendered in the agent's accent color. Sections appear in this order, and any empty section is omitted:

• Description — the agent's wrapped description.
• Live state — a ● current agent line when the inspected agent is the one currently running.
• Model / Fallback / Thinking — the provider/model, any fallback models, and the gauge + value thinking line (omitted for models with no selectable thinking, e.g. harness-backed agents).
• Context — the agent's latest known context usage, e.g. Context: 12.8K of 128.0K tokens (10%) (a bare token count when the context limit is unknown; omitted until the agent has run). Sub-agent and background-agent runs are accounted for.
• Sub-agents (N) / Handoffs (N) / Skills (N) — compact, inline, comma-separated lists wrapped to the dialog width.
• Limits — the configured per-agent limits that are set, e.g. Limits: max-iter 50 · history 40 · max-tool-calls 5.
• Options — the enabled option flags, e.g. Options: add-date · add-environment-info · redact-secrets.
• Toolsets (N) — one line per toolset with a status marker, its name, kind, and tool count, followed by the indented tool names.
• Commands (N) — the slash commands the agent defines, each with its description.

Each toolset carries a single-width status marker reflecting its live lifecycle: ● started (serving), ○ stopped (not yet started), or ⚠ error. The tools listed under a toolset are the live tool names when it has started; for a toolset that has not started, the inspector instead shows its declared tools: allow-list prefixed with declared: (and shows nothing when the toolset declares no allow-list and therefore serves every tool). This lets you see both what an agent is configured with and what is actually running, even before the agent has been used.

The dialog scrolls when the content is long; press Esc to close it. Remote runtimes (which hold no local team config) degrade gracefully — the config-derived sections are simply omitted.

Model identifiers on line 2 are truncated from the left (e.g. …claude-sonnet-4-6) only when they overflow, so the informative tail (variant/version) is preserved. As the sidebar narrows the model keeps its own line, and near the minimum width line 1's gauge collapses to a single cell to keep the name readable.

The thinking state of each model is shown with a gauge + value on the card and a gauge or badge on the row (no ✻ glyph):

The effort gauge is a fixed-width six-cell indicator (▰ filled, ▱ empty) so the badge column stays aligned. It maps the six selectable levels one-to-one onto filled-cell counts — minimal → ▰▱▱▱▱▱, low → ▰▰▱▱▱▱, medium → ▰▰▰▱▱▱, high → ▰▰▰▰▱▱, xhigh → ▰▰▰▰▰▱, max → ▰▰▰▰▰▰ — so the cell count alone is lossless, with a low→high color ramp as a secondary cue. A capable-but-disabled model shows a dim empty gauge (▱▱▱▱▱▱ off), adaptive budgets show auto, and token budgets keep ◉ <count>. The same gauge + value renders on the focus card, the Agent Inspector, and the row.

Harness-backed agents (e.g. claude-code) show the harness type as their model and no thinking gauge. Press Shift+Tab to cycle the current model's thinking-effort level; a ✻ Thinking: <level> toast confirms the change (useful when the sidebar is hidden).

Agent Delegation Feedback

When a parent agent calls transfer_task to delegate work to a sub-agent, the TUI provides live visual feedback in both the sidebar and the chat.

Sidebar — Transfer box: As soon as the delegation starts, an animated Transfer box appears below the agent roster, showing the direction of the handoff with a traveling dot:

╭─ Transfer ─────────────────╮
│  parent  ●──────►  child   │
╰────────────────────────────╯

The box stays visible for at least 1.5 seconds. Once the sub-agent produces its first message, reasoning, or tool output, the box hides (still honoring the minimum window) to keep the sidebar focused on the active agent. If the sub-agent is slow or silent, the box hides after a 3-second maximum cutoff. The header shows a ↔ marker while any delegation is still in flight, even after the box hides.

Sidebar — Return box: When the sub-agent finishes and control returns to the parent, a brief Return box animates the reverse direction for up to 1.5 seconds, then disappears:

╭─ Return ───────────────────╮
│  child  ●──────►  parent   │
╰────────────────────────────╯

Chat — return transition: Alongside the sidebar Return animation, the chat shows a one-line static transition between the two agent badges:

[child]  returned control to  [parent]

This transition is not persisted — it does not reappear when you reload the session.

Context-Usage Gauge

The context percentage shown in the sidebar token-usage section, and the fill bar in the lean TUI status line, both color-escalate as the active session approaches the auto-compaction threshold:

While a compaction is running the percentage is replaced by a "compacting…" indicator; token counts remain visible in the lean TUI status line.

The thresholds are proportional to the agent's configured compaction_threshold (default 0.9), so a custom value keeps a predictable visual runway. See Compaction Threshold for configuration details.

Thinking and Tool Details

Reasoning/thinking blocks are collapsed by default and carry a Thinking header badge. When collapsed, the TUI shows a short preview and compact tool summaries. Expand a block to see the full thinking content and the real tool renderers, including detailed tool output such as file edit diffs.

To start new sessions with thinking/tool blocks expanded by default, set expand_thinking in your user config:

# ~/.config/cagent/config.yaml
settings:
  expand_thinking: true

Set it to false or omit it to keep the default collapsed behavior.

Snapshots, /undo, and /snapshots

Enable shadow-git snapshots globally in ~/.config/cagent/config.yaml:

settings:
  snapshot: true

When enabled, docker-agent records filesystem snapshots at turn boundaries. The TUI exposes two slash commands that operate on those snapshots:

• /undo restores files from the most recent snapshot (one step back).
• /snapshots opens a dialog showing how many snapshots have been captured and the number of files in each one. Use ↑/↓ (or j/k) to highlight an entry, then press r to reset the workspace to that point. Pick <original> to revert every snapshot and bring the workspace back to its pre-agent state. Esc closes the dialog without changing anything.

Neither command removes messages from the session transcript — they only touch files on disk. Both commands (and the matching command-palette entries) are hidden when snapshots are turned off. Omit snapshot or set it to false to leave automatic snapshots off; agents can still configure snapshot hooks manually.

See Snapshots for how the shadow-git machinery works and how to wire it per-agent.

File Attachments

Attach file contents to your messages using the @ trigger:

1. Type @ to open the file completion menu
2. Start typing to filter files (respects .gitignore)
3. Select a file to insert the reference

# In the chat input:
Explain what the code in @pkg/agent/agent.go does

The agent receives the full file contents in a structured <attachments> block, while the UI shows just the reference.

Attached files are also recorded on the session so sub-agents spawned by task transfer can read them. To review what is attached, open /context: the dialog lists every attached file (and resolved prompt file) with a per-file token estimate. Use ↑/↓ to select an attached file and press d (or x/Del) to drop it, or run /drop <path> directly. Dropping stops sharing the file with sub-agents and skills; content already inlined in earlier messages stays in the conversation until compaction, and the file can always be re-attached with @ or /attach.

Team Context Budgets and Targeted Compaction

The /context dialog also shows a Live sessions section: the current session plus every currently running sub-agent session (foreground children spawned by task transfer and long-running run_background_agent tasks). Each row shows the agent name, a short session ID (so two concurrent runs of the same agent stay distinguishable), and that session's context budget: used tokens, context limit, and percentage, or an explicit "limit unknown" reading when the model's window cannot be resolved.

Select a live session with ↑/↓ and press Enter to explicitly compact it. Cross-agent compaction happens only on this explicit request: no idle-triggered automatic compaction is added, and the existing automatic threshold and overflow-recovery compaction of sub-agent sessions is unchanged. The request is queued onto the target session's own run loop and executes at the next safe point between model turns, so it cannot corrupt an in-flight turn. The dialog closes and a notification confirms the request; a second notification reports the outcome (compacted, skipped, or failed) with the agent's name. Selecting the main row runs the same compaction as /compact. /compact itself keeps compacting the current root session. Remote runtimes do not expose live-session tracking, so the section is omitted there.

Runtime Model Switching

Change the AI model during a session with /model or Ctrl+M:

1. Press Ctrl+M or type /model
2. Select from config models or type a custom provider/model
3. The model switch is saved with the session and restored on reload

When a models gateway is configured (--models-gateway) and it exposes an OpenAI-style /v1/models endpoint, the picker lists the models actually served by the gateway (merged with the models defined in the agent config). When the gateway doesn't expose /v1/models, the picker falls back to the regular catalog.

The picker's catalog entries come from models.dev and are cached locally for a day. Press Ctrl+R in the picker to force model discovery to run again, including a refetch of the models.dev catalog.

Tip

Use model switching to try a more capable model for complex tasks, or a cheaper one for simple queries — without modifying your YAML config.

Editable Messages

Edit any previous user message to branch the conversation. Hover a past user message and click ✎ edit (or select it with the keyboard and press e) to modify it — the agent will re-process from that point, while the original session history is preserved. This is great for exploring alternative approaches without losing your work.

Hovering a user or assistant message also reveals a ⎘ copy button that copies the message text to the clipboard (c when a message is selected).

Error Recovery

When an agent turn fails (fatal model error, hook block, loop detection, tool-setup failure), the TUI displays the error in the message stream and persists it to the session store. Errors survive a reload and are shown exactly where they occurred, making them visible in shared or remote sessions.

Each error message includes a clickable ↻ retry button. Clicking it resumes the conversation from the point of failure — without retyping your last message. This lets you recover from transient failures (rate limits, network blips, model API errors) in one click.

Session Management

docker-agent automatically saves your sessions. Use /sessions to browse past conversations:

• Browse past sessions with search and filtering
• Workspace grouping: sessions started in the current directory are listed first under "This workspace", everything else under "Other locations" with its originating directory shown next to each entry; press Ctrl+G in the browser to cycle between all, current-directory only, and other-directory views. Restoring a session reopens it in its original directory, so the label always matches where a restore will land
• Star important sessions with /star
• Branch conversations by editing any previous user message — preserving the original session history
• Resume sessions with docker agent run config.yaml --session <id>
• Relative refs: --session -1 for the last session, -2 for the one before

Session Title Editing

Customize session titles to make them more meaningful and easier to find. By default, docker-agent auto-generates titles based on your first message, but you can override or regenerate them at any time.

Using the /title command:

/title                     # Regenerate title using AI (based on recent messages)
/title My Custom Title     # Set a specific title

Using the sidebar:

1. Click the pencil icon (✎) next to the session title in the sidebar
2. Type your new title
3. Press Enter to save, or Escape to cancel

Note

Manually set titles are preserved and won’t be overwritten by auto-generation. Title changes are persisted immediately to the session.

Keyboard Shortcuts

Press Ctrl+H to view the complete list of all available keyboard shortcuts.

Custom Keybindings

You can remap the shortcuts above by adding a keybindings list to the settings block of your ~/.config/cagent/config.yaml. Each entry maps an action to one or more key combinations in Bubbles key format (for example ctrl+q, alt+enter, f2). Unlisted actions keep their defaults.

This is the recommended way to replace the Ctrl+J newline fallback, which conflicts with common editor/terminal shortcuts (for example inside VS Code).

settings:
  keybindings:
    # Insert a newline with Alt+Enter instead of Ctrl+J. Shift+Enter still
    # works automatically on terminals that report it.
    - action: "editor_newline"
      keys: ["alt+enter"]
    # Allow several keys for one action.
    - action: "commands"
      keys: ["f2", "ctrl+k"]
    - action: "quit"
      keys: ["ctrl+q"]

Valid actions:

Shift+Enter for newline is detected from your terminal's capabilities and is always available where supported, independent of editor_newline.

Invalid entries are ignored with a warning (visible with --debug) so a bad config never breaks the TUI: unknown actions, empty or malformed keys, and keys that would collide with another action are dropped while every other binding keeps working.

History Search

Press Ctrl+R to enter incremental history search mode. Start typing to filter through your previous inputs. Press Enter to select a match, or Escape to cancel.

Settings

Run /settings to open the settings dialog. Use Tab to switch between Appearance, Behavior, and Notifications.

The Appearance tab selects the theme and customizes the layout. Layout changes show a live schematic preview and apply immediately to the UI behind the dialog:

• Sidebar position: Right (default), Left, Top, or Bottom. Left/right keep the full vertical sidebar next to the chat; top/bottom render it as a compact horizontal band above or below the chat (session title, working directory, usage, plus a one-line summary of the current agent, tools, and todos).
• Section spacing: Compact, Normal (default), or Relaxed, the number of blank lines between the sidebar sections (1, 2, or 3).
• Sidebar sections: toggle the visibility of the Session path (the working directory line, including its git branch) and the Token usage, Agents, Tools, and Todos sections. The session title is always shown.

Appearance also controls split-diff rendering, expanded thinking, and whether tool results are hidden by default. Select Theme to open the theme picker.

The Behavior tab controls busy-message handling, the auto-approve default, tab restoration, automatic snapshots, lean UI, and the maximum tab-title length. Restore-tabs and lean-UI changes take effect on the next launch. Enabling auto-approve requires confirmation.

The Notifications tab enables completion sounds and sets the minimum task duration before a sound plays.

Press Enter to apply and persist, or Escape to cancel and restore the previous layout. The settings are saved globally in ~/.config/cagent/config.yaml:

# ~/.config/cagent/config.yaml
settings:
  busy_send_mode: queue # steer (default), queue
  layout:
    sidebar_position: left # right (default), left, top, bottom
    section_spacing: compact # normal (default), compact, relaxed
    hide_session_path: false
    hide_usage: true
    hide_agents: false
    hide_tools: false
    hide_todos: false

Theming

Customize the TUI appearance with built-in or custom themes:

# Open Settings and select Theme under Appearance
/settings

Built-in Themes

default, default-light, catppuccin-latte, catppuccin-mocha, dracula, gruvbox-dark, gruvbox-light, nord, one-dark, solarized-dark, tokyo-night

Auto Theme (match the terminal)

The special theme auto follows the terminal's light/dark background instead of naming a fixed theme. Select Auto (match terminal) from Settings → Appearance → Theme, pass --theme auto, or set it in your user config:

settings:
  theme: auto
  theme_dark: default # optional, theme used on dark backgrounds (default: default)
  theme_light: default-light # optional, theme used on light backgrounds (default: default-light)

At startup the terminal background is queried (OSC 11) to pick the dark or light theme of the pair; non-interactive runs (pipes, CI) fall back to the dark theme. In terminals that report appearance changes (DEC mode 2031 — Ghostty, kitty, contour, …), flipping the OS or terminal appearance while docker-agent is running switches the theme live. Terminals without that mode re-sync when the window regains focus.

Custom Themes

Create theme files in ~/.cagent/themes/ as YAML. Theme files are partial overrides — you only need to specify the colors you want to change. Any omitted keys fall back to the built-in default theme values.

# ~/.cagent/themes/my-theme.yaml
name: "My Custom Theme"

colors:
  # Backgrounds
  background: "#1a1a2e"
  background_alt: "#16213e"

  # Text colors
  text_bright: "#ffffff"
  text_primary: "#e8e8e8"
  text_secondary: "#b0b0b0"
  text_muted: "#707070"

  # Accent colors
  accent: "#4fc3f7"
  brand: "#1d96f3"

  # Status colors
  success: "#4caf50"
  error: "#f44336"
  warning: "#ff9800"
  info: "#00bcd4"

# Optional: Customize syntax highlighting colors
chroma:
  comment: "#6a9955"
  keyword: "#569cd6"
  literal_string: "#ce9178"

# Optional: Customize markdown rendering colors
markdown:
  heading: "#4fc3f7"
  link: "#569cd6"
  code: "#ce9178"

Applying Themes

In user config (~/.config/cagent/config.yaml):

settings:
  theme: my-theme # References ~/.cagent/themes/my-theme.yaml

At launch: Pass --theme <name> to docker agent run to preselect a theme for that session. This overrides settings.theme in your config but is not saved. Invalid theme names print an error at startup listing the available options. Has no effect in --exec mode. --theme auto enables the auto theme for the session.

At runtime: Open /settings, select Theme on the Appearance tab, and choose from the available themes. Your selection is saved globally in ~/.config/cagent/config.yaml under settings.theme and persists across sessions.

Tip

Hot Reload

Custom themes auto-reload when you save changes to the file — no restart needed. This makes it easy to tweak colors in real-time.

Warning

Partial overrides

All user themes are applied on top of the default theme. If you want to customize a built-in theme (e.g., dracula), copy its full YAML from the built-in themes on GitHub into ~/.cagent/themes/ and edit the copy. Otherwise, omitted values will use default colors, not the original theme's colors.

Tool Permissions

When an agent calls a tool, docker-agent shows a confirmation dialog by default. You can:

• Approve once — Allow this specific call
• Always allow — Permanently approve this tool/command for the session
• Deny — Reject the tool call

Granular permissions: The permission system supports pattern-based matching. When you “Always allow” a specific tool command, only that exact pattern is auto-approved — other commands from the same tool still require confirmation. This lets you auto-approve safe, read-only operations while maintaining control over destructive ones.

Tip

YOLO mode

Use --yolo or the /yolo command to auto-approve all tool calls. You can also toggle this mid-session. For aliases, set --yolo when creating the alias: docker agent alias add fast agentcatalog/coder --yolo.

Notifications

The TUI displays transient notification banners for agent warnings, errors, and other runtime events. Notifications auto-dismiss after a short delay unless the mouse is hovering over them — hovering pauses the timer so you have time to read the message.

Hint text in the top-left corner of the notification border shows the available actions at a glance.