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"

# 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"

Slash Commands

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

Thinking and Tool Details

Reasoning/thinking blocks are collapsed by default. 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.

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.

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

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.

Session Management

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

• Browse past sessions with search and filtering
• 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.

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.

Theming

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

# Switch themes interactively
/theme

Built-in Themes

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

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