bonsai

TUI guide

The terminal UI is a single-binary ratatui application: transcript, composer, status surfaces, a plan canvas, and a set of modals. This page is the user reference; the rendering architecture is summarized at the end.

Layout

A vertical stack: header (1 row) → main area → composer (4 rows)

The header shows the bonsai brand, session id and status, workspace badges (cwd, git branch, elapsed), and a right-pinned context chip — a fill bar showing context usage percent and cost, colored by pressure (green < 70%, amber ≥ 70%, escalating to red ≥ 95%). Click it to open /ctx. While a run is active the elapsed badge also carries the clock the session budget is charging — ⏱ 12m 4s · compute 9m 12s · wait 2m 51s; see Runtime timing.

The status line (under the composer) shows: a state dot (spinner while busy), active agent, model — then only deviations from defaults: reasoning, smol, serenity, the autonomy marker (amber rising to red at yolo), and the sandbox posture. Attachment chips, queued-message hints, and waiting peers appear on the same line. The terminal title mirrors state: [!] bonsai · <title> when a modal needs attention, a spinner while busy.

Switching persona mid-run never cancels the run — peeking at the plan canvas while the coding agent works is always safe. The status line shows the pending switch as Running → Selected (e.g. Coding → Planning); the new persona — and its per-mode model — applies when the run finishes or is interrupted, and the next message you send runs under it.

Transcript

Use /goal <objective> for work with a persistent objective. /goal status shows its state and stop reason; /goal pause, /goal resume, and /goal clear control it while retaining the conversation. Messages sent during work steer the active objective. A restored session waits for explicit /goal resume.

Goal questions can remain pending while the agent does independent work. Tab hides the question so you can type; /questions brings it back. The recommended choice is assumed after 60 seconds unless the question declares another timeout. Enter answers and Esc cancels. See persistent goals for lifecycle and limits.

Item types: user messages, queued user messages, assistant text (markdown with syntax-highlighted code fences), reasoning summaries, tool cards, execution groups, command output, diffs/edit cards, todo updates, completion reports, errors, and blue peer-message cards.

Serenity mode

/serenity toggles a calm, presentation-only view — behavior, stored transcript, and reasoning settings are untouched. While the model reasons you see an animated placeholder instead of streaming thought text; finished thoughts settle into a bucketed label (“Quick thought” … “Went deep”). Multi-tool groups fold to their one-line summary. Nothing is lost: Enter opens the full reasoning, and copying copies the real text. The choice is a global preference and survives restarts.

Accessibility

--reduced-motion freezes spinners and shimmer animations; --screen-reader switches to a linear labelled transcript in the normal buffer without mouse capture or the alternate screen. Monochrome and high-contrast theming are covered in Theming.

Composer

Keybindings

Keybindings are fixed (no user keymap file). The essentials:

Key Action
Ctrl+C staged: cancel the run tree → arm exit → confirm exit
Ctrl+Q quit
Enter while running queue the draft for the next turn
Tab accept completion or cycle focus: composer → transcript → sidebar/plan
Shift+Tab cycle persona (coding → plan → enabled custom agents); each mode brings its own model, and switching never cancels a running turn
1 / 2 (outside composer) agent / plan view
Alt+M cycle autonomy (never lands on yolo)
Alt+I implement plan (/start)
Alt+T / Alt+S tasks view / subagents view
Ctrl+G (or /select) copy mode: release mouse capture for native terminal text selection (toggle; a ⊙ select marker shows while it’s on)
Ctrl+T cycle focus pane
Ctrl+End jump transcript to latest
Esc while running if a message is queued, steer it by stopping only the foreground turn; never submits the live draft
Esc otherwise progressive: dismiss popup → clear selection → clear draft → close modal

Full editing/selection/scroll tables are in /keys inside the app.

Modal conventions: Esc/q close, Enter confirms, arrows move, PgUp/PgDn scroll. Permission prompts use a (once), s/m (session), p (project), d (deny); sandbox-escape prompts have no project option. In the model picker, ←/→ switch the provider/model/reasoning panes and a bare letter in the reasoning pane binds a model shortcut. In the /ctx ledger view: p pin, d drop, s stub, r restore.

Modals and pickers

Onboarding wizard, help (/help, /keys), model picker, theme picker (live preview), settings, mode picker, all permission prompts (command, sandbox escalation, web domain, MCP tool, hook trust, question, API key), agent browser + composer wizard, subagent view, task list, peer list, /ctx context inspector, episodes, usage dashboard, session picker, plan pickers and confirms, review-scope picker, provider manager + local-model wizard, MCP servers, skill manager, memory manager + add wizard, sandbox status, and detail overlays (tool, block, diff, plan finding). Every prompt modal triggers the [!] terminal-title attention marker.

Rendering architecture (brief)