Terminal UI (TUI)

cagent’s default interface is a rich, interactive terminal UI with file attachments, themes, session management, and more.

Launching the TUI

# Launch with a config
$ cagent run agent.yaml

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

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

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

Slash Commands

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

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

cagent 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 cagent 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, cagent 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

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