Terminal UI¶

The Terminal UI is the place to work with Colossus in a conversation. You can send prompts, watch tools run, answer questions, and approve individual actions without leaving the terminal.

Start in a workspace¶

colossus -w /absolute/path/to/repository

colossus tui opens the same interface. A fresh session shows your workspace, model route, approval mode, and readiness state above the composer. Type a task and press Enter to start. For example:

Explain how this repository handles configuration. Show me the relevant files.

The transcript appears above the composer as work progresses. The TUI fills the alternate screen by default; use the mouse wheel or PageUp/PageDown to read older output and End to return to live output. Exiting restores your prior terminal view.

The top bar shows the workspace, session, and installed version when there is enough vertical space. The composer has a neutral background that separates your draft from the conversation. A single status row below it highlights the mode and security warnings, alongside readiness, approval handling, the model route, and context budget. Smaller widths shorten or omit runtime details to keep status and warnings readable. Compact terminals omit the top bar.

Use --no-alt-screen for an inline interface that leaves completed output in your terminal's normal scrollback:

colossus -w /absolute/path/to/repository --no-alt-screen tui

To return to the latest conversation, start with tui --resume. Use tui --session SESSION_ID when you know the exact session. Inside the TUI, /resume opens a searchable session browser.

Find your way around¶

Enter a slash command in the composer. These are useful starting points:

Type / to complete commands. Type @ at a skill token to choose an active plugin skill. Use Up/Down to browse suggestions and Tab to accept one. For every command and key, see TUI commands and keys. See Context and snapshots to read the budget and manage long-session history.

Write and review a turn¶

Enter sends the current prompt. Shift-Enter adds a new line when your terminal reports that key combination. Ctrl-J also adds a new line, including in terminals that send Shift-Enter as plain Enter. Use /multiline to choose Enter behavior: Enter can add lines while Ctrl-D sends the prompt. Direct shortcuts such as /multiline on and /multiline off remain available.

/permissions opens an approval-mode chooser with the current mode highlighted. Up/Down moves the selection, Enter applies it, and Esc returns without changing anything. This changes approval handling for subsequent operations in this TUI process; policy, tool authority, and sandbox boundaries still apply. /stream, /events, /reasoning, /transcript, and /provider diagnostics use the same chooser. Slash completion shows each setting once; type the setting followed by a space to see direct argument shortcuts. /theme list and other theme tools remain available alongside the theme picker.

You can continue typing while a run is active. Colossus queues up to eight future turns; after a failure or cancellation, it pauses the queue for your decision. Use Ctrl-R to open full-screen prompt history. Type to filter, use Up/Down to choose, and press Enter to place a prompt in your draft. Esc keeps the draft you had before opening history. To include a supported image, use /attach PATH, inspect the queue with /attachments, and remove one with /detach INDEX.

When an action needs approval, a decision dock opens above the preserved draft. Read the summary, inspect the exact request and protections if needed, then select a decision and press Enter. There is no preselected approval: dismissing the dock, disconnecting, or waiting until it times out denies the request. /permissions shows the current mode; the access and approvals guide explains the modes and their limits.

For a multi-step change, /plan new starts a plan you can review before execution. The Planning guide covers approving it and choosing Direct or Goal Mode. For source-backed questions, see Research.

Leave and come back¶

Press Ctrl-C while idle, or enter /exit, to leave the TUI. During an active run, the first Ctrl-C requests cancellation; a second exits. Your session remains available. Reopen the latest one with:

colossus -w /absolute/path/to/repository tui --resume

If you cannot find earlier work, check that you are using the same workspace and configuration. Sessions shows how to list and resume a specific ID.

Restore in Herdr¶

When an interactive TUI starts inside a Herdr pane, Colossus reports its current session and whether it is idle, working, or waiting for a decision. Herdr 0.9.2 or later can reopen that session after a server restart with the same workspace, configuration, approval mode, and screen mode. Switching sessions updates the restore command, and exiting Colossus releases the pane. Check the integration with herdr pane get "$HERDR_PANE_ID" or herdr agent list.

If the TUI is connected to an active worker, --approval-mode sets the mode for that TUI client without changing the worker default for other clients.

What's next?¶