TUI commands and keys¶

Start with colossus or colossus tui. The default inline viewport commits every finalized transcript entry to native terminal scrollback immediately, so ordinary mouse selection, copy, search, and wheel scrolling keep working. The viewport expands while output is streaming, then collapses back to the sticky composer and status as soon as that output completes without inserting cleared live rows between transcript entries. Use --alt-screen for the application-owned full-screen transcript viewport; --no-alt-screen remains a compatibility alias for the default.

Fresh empty sessions initially use that live viewport for the Launch Rail: a responsive, non-durable welcome surface with the selected workspace, provider route, sandbox profile, approval mode, and readiness state plus shortcuts for /plan, /resume, and /tools. It is never committed to native scrollback or canonical session history. The first submitted command or prompt dismisses it before normal output is rendered; restored sessions skip it entirely. Inline startup first moves the prior visible terminal into native scrollback, then draws from a clean viewport without purging the terminal's earlier history.

The current directory or -w, --workspace selects repository context, relative-path anchoring, and state identity. It is also the resource boundary under workspace isolation, but not under acknowledged full access. Configuration and workspace-partitioned state follow the Colossus home resolution contract. Every top-level interactive run also snapshots the bounded home and repository AGENTS.md instructions before its first provider turn.

With --approval-mode risk-auto, successful low-risk reviews appear as non-blocking Automatic approval review transcript cards. They do not take focus from the composer or require a response.

Evaluator outages and invalid assessments appear as non-blocking Automatic approval review failed cards before the explicit approval dock opens above the composer. These cards contain only a sanitized failure category, action, resource, and manual-fallback explanation.

Security posture findings appear at startup as a non-durable Security posture warning card and remain visible as a warning count in the footer. Each finding is a primary risk line followed by a dim, concise recommendation. This includes an explicit danger_full_access sandbox backend even when its boundary acknowledgement is already configured. A quiet row separates startup guidance from the composer. The footer is a full-width contrasting status surface; an active security count is a distinct warning-colored lead segment.

Effect approvals use a compact bottom-docked, focus-taking surface that keeps the current transcript visible and the composer draft preserved. Summary presents the released actor, action, resource, policy reason, and risk metadata as borderless rows so the decision context is visible without opening a nested table; long values wrap and remain scrollable. Exact request shows the bounded prepared request, with any 65,536-character display truncation marked explicitly, and repeats the complete sanitized approval scope before confirmation. Protections explains request binding, one-use behavior, policy re-evaluation, and the enforcement layers that remain active. Section and decision controls use filled, theme-resolved surfaces so focus remains visible without implying approval. Inline mode renders this transient dock on a temporary terminal screen, so dismissing it restores native scrollback byte-for-byte.

Keys¶

Typing / at the beginning of a draft opens slash-command completion. Typing @ at a skill-token boundary opens skill completion. Suggestions are bounded and dismiss until the draft changes after Esc.

In inline mode, the session and theme browsers open on a temporary alternate screen. Closing either restores the inline viewport and native terminal history byte-for-byte, so browser rows never become scrollback output. Theme navigation is a reversible live preview: Esc restores the original theme and only Enter saves the selection.

Commands¶

The in-product /help command is generated from the current completion catalog and is the executable authority for available command families and required arguments in the current runtime.

Use /resume or /session resume without an ID for the searchable master-detail browser; exact session IDs are accepted when deterministic selection matters. The browser keeps the running-command row, composer draft, and status footer visible while it is open.

Image attachments¶

/attach PATH accepts an absolute path or a path relative to the active workspace; surround a path containing spaces with quotes. /attachments lists the pending images, and /detach INDEX or /detach all removes them. Execute and Plan modes accept images; Research mode rejects them locally. Pending images remain queued when validation or run start fails and clear after the submission is accepted.

The composer shows up to three pending thumbnails and collapses the remainder into a +N more indicator. Submitted images retain content order and an adjacent filename, MIME, dimensions, size, and digest card. Default inline mode always renders deterministic half-block previews so native scrollback remains stable. --alt-screen uses Kitty, iTerm2, or Sixel when a capability query succeeds and falls back to half blocks.

Plan workflow¶

The terminal starts in Execute mode. Plan mode and its selected plan are process-local: they are not presentation preferences and are not restored after a restart. The mode survives a session switch, but the selection is cleared so a plan from one session cannot become authority in another. The footer and composer title show the current mode, selected plan, status, and revision when space permits.

Submitting a prompt in Plan mode creates a new Draft when nothing is selected. With a selected Draft, the prompt refines that exact revision. Each completed planning turn opens a review dock with Keep refining, Approve, and Discard choices. The dock previews the structured Plan steps and clarifies that durable Tasks are separate records. Approving flows directly into the existing Direct/Goal execution dock. An Approved plan cannot be refined; use /plan execute, /plan new, /plan discard, or /plan off. Concurrent changes reject the stale revision. Reload the current record explicitly with /plan use PLAN_ID before retrying.

Canceling the execution decision dock, or cancellation/failure before plan consumption, keeps the mode and selection. The dock preserves the composer draft and requires an explicit Direct or Goal selection before Enter can start execution. Once Direct execution or Goal handoff commits consumption, the terminal returns to Execute mode and clears the selection even if later work fails or is cancelled. The consumed plan and completed, cancelled, or failed evidence remain inspectable. A cancelled or failed Goal stays Active; /goal resume GOAL_ID uses only its remaining iteration budget.

/events compact shows only a short preview of raw web.fetch, docs.fetch, and network.http response bodies. Use /events verbose when inspecting the full released response is necessary. Verbose run-error cards also show a structured HTTP status field when an upstream provider returned a non-success response. Ordinary run errors remain body-free. /models doctor [PROFILE] issues a new representative tool-calling probe and displays its exact credential-free request plus at most 16 KiB of the redacted non-success response body. /provider doctor [PROFILE] does the same for provider catalog diagnostics.

Doctor commands cannot reproduce a failure that occurs only on a later continuation. Run /provider diagnostics on, retry the failing TUI turn, and inspect the error card's response body, offered tool-name list, and exact provider-facing request. The setting lasts only for the current TUI process and applies to every provider turn until /provider diagnostics off or exit. The detailed evidence is not written to durable run history, but the request can contain user, session, and tool-result data; review it before sharing. Use /events off to hide successful tool results entirely.

/research QUESTION uses standard depth with the repo, web, and mcp lanes. Use the CLI research run route when depth or lane selection must be explicit.

Interaction contract¶

• Input stays available during a run; up to eight future turns may queue.
• Mode and lifecycle commands share that FIFO. Returned plan state is applied before the next item starts, and the queue does not drain while the execution-choice overlay is open.
• A failure or cooperative cancellation pauses the queue for explicit confirmation.
• Effect approval uses a focus-taking bottom dock; user.ask retains its one-use overlay. Both preserve the draft.
• Blank, cancelled, timed-out, disconnected, replayed, or malformed prompt answers fail closed.
• New output does not move an operator reading older content; the UI shows a new-item count.
• The transcript reflows on resize. Composer and footer remain pinned.
• Terminal state, cursor, bracketed paste, raw mode, and screen ownership are restored when the TUI exits.

Non-TTY stdin selects a bounded line runner. It does not own terminal control and is appropriate for automation.