The TUI in Depth

Caliban's interactive mode is a full-screen terminal UI built on ratatui + crossterm. This chapter covers everything that goes beyond the basics introduced in The Interactive TUI.

Layout

The screen is divided into three regions from top to bottom:

┌─────────────────────────────────────────────────────┐
│                                                     │
│   Transcript / output region  (flex-grow)           │
│                                                     │
├─────────────────────────────────────────────────────┤
│   Input area (2 rows)                               │
├─────────────────────────────────────────────────────┤
│   Status bar (1 row)                                │
└─────────────────────────────────────────────────────┘

The input area sits between the transcript and the status bar, placing the prompt visually close to the context information below it.

Status line

The status bar shows cwd · provider model · session (turns) · running… during a live turn. When caliban is idle the spinner disappears and the elapsed-turn time is shown instead.

A custom prefix segment can be prepended by configuring a shell script in settings (see Settings Reference for the statusLine key). The script runs off-thread after each turn completes; its output is cached so it never blocks rendering. Use /statusline to inspect the active configuration.

Keybindings

Overlays

Overlays are modal popups rendered centered (approximately 80% × 80%) over the main view. Press Esc or q to close any overlay. The active input bar is suppressed while an overlay is open.

Available overlays and how to reach them:

Editor modes

Caliban's input bar uses emacs-style key bindings by default (Ctrl+A / Ctrl+E for line start/end, Ctrl+K to kill to end-of-line, etc.).

External editor handoff

Ctrl+G writes your current input buffer to a temp file, suspends the TUI (leaving the alternate screen), execs $VISUAL / $EDITOR / vi with the file as the argument, then reads the result back and re-enters the TUI. Multi-word editor values like EDITOR='code --wait' work because the value is split on whitespace without shell parsing.

Transcript viewer

Ctrl+O opens the transcript viewer overlay. It renders every ContentBlock in the conversation history — text, tool calls, tool results, thinking blocks, and images — as the model sees them.

Following background bash (Ctrl+B)

Background bash lets caliban run a shell command in the background while you continue interacting with the agent. Press Ctrl+B inside the TUI to open or follow the background bash output panel. The agent can launch background bash tasks via Bash{background:true}; the TUI surfaces their output through the same panel.

Reverse history search

Ctrl+R opens inline reverse search over the current session's prompt history, showing matches as you type. Ctrl+S cycles the scope outward:

Ctrl+R  →  session scope
Ctrl+S  →  project scope  →  all-projects scope

Wider scopes are loaded lazily in a background task (budget: 2 s). History is persisted per project.