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 are queued and processed in order. This means you can invoke a slash command to interrupt or direct the agent even while it is mid-response.

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

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.

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.

Editable Messages

Edit any previous user message to branch the conversation. Click on a past message 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.

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

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.

Layout Customization

Run /custom to open the layout dialog. It shows a live schematic preview of the resulting layout and applies every change 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 Token usage, Agents, Tools, and Todos sections. The session block (title and working directory) is always shown.

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:
  layout:
    sidebar_position: left # right (default), left, top, bottom
    section_spacing: compact # normal (default), compact, relaxed
    hide_usage: true
    hide_agents: false
    hide_tools: false
    hide_todos: false

Theming

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

# Switch themes interactively
/theme

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) in the /theme picker, 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: Use the /theme command to open the theme picker and select from available themes. Your selection is saved globally in ~/.config/cagent/config.yaml under settings.theme and persists across sessions.

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.

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.