Skip to main content
Run cortex in a terminal and you get the interactive app: a timeline of the conversation and the agent’s work, a composer at the bottom with a mode chip on its top border and a model chip on its bottom border, and a footer strip of the shortcuts that apply right now. It takes the whole viewport by default and gives your scrollback back when you leave. This page covers how to start it, what each region of the screen shows, the timeline rows and tool tiles, the composer and its sigils, queueing a follow-up while a turn runs, the panels and overlays, and how to interrupt or quit. The controls that decide what the agent is allowed to do are on Modes and permissions.

​
Start it

The TUI needs a real terminal on both standard input and standard output. If either is redirected it refuses to start and points you at cortex run or cortex exec instead.

​
The first screen

Before your first turn the timeline shows a two-line welcome:
On a first run a tips panel appears with it. It points you at switching model and reasoning effort, adding @ files for context, pressing Shift+Tab to cycle Agent / Plan / Ask, and opening Settings with F2. A narrow terminal gets a shorter variant of the same welcome. After your first turn the welcome is dropped: an empty session is composer and footer only. The TUI deliberately never paints a fake shell prompt, an echoed command, a working directory or a logo.

​
The screen, region by region

The stage on the status line reads Thinking, Executing with the tool name, Streaming or Delegation.
The token counter is a pair of numbers, not a promise. The real context window depends on the model you are using, and the counter can read zero until the first turn finishes. Treat the figure on screen as informational.

​
Timeline rows and tool tiles

Tool rows collapse to a summary. With the timeline focused, press e to expand or collapse the selected one. The exact wording of the elapsed-time and token rows is still settling, so do not script against it.

​
The composer

  • Enter sends. Alt+Enter inserts a newline. ↑ and ↓ walk your prompt history, and ↑ on an empty composer edits your last message.
  • The mode chip sits on the top border and the model chip on the bottom border, drawn as the model’s name with its reasoning effort in brackets, for example Cortex Mini 1 (medium).
  • A goal, if the session has one, adds a chip immediately after the mode chip.
Four characters at the start of a line open something instead of being sent as text: The placeholder tells you what the composer will do with what you type:

​
Queue a follow-up while a turn runs

You do not have to wait for a turn to end. Type while it runs and Enter queues the message instead of sending it; the composer shows how many are waiting, and ↑ edits a queued message. The queue is sent in order as the turn frees up. Esc interrupts the turn instead. The timeline records × Stopped, and the composer invites you to reply or edit your last message. The footer strip changes with what is on screen. Two examples, exactly as they are drawn:
Every context gets its own strip: idle, text typed, a narrow terminal, a turn running, the queue, the model and effort lists, an approval prompt, the MCP and plugins panels, the resume picker, Bash mode, the command palette, the undo sheet, a rate limit, a feature that is unavailable, and more besides. The strip shows the keys that apply at that moment; it is not the complete list of bindings. For that, use the shortcuts sheet, or see CLI keyboard shortcuts.

​
Panels and overlays

Most of the surface area is one slash command away. Panels title themselves with a count, in the pattern MCP servers · 2 of 4 connected. A list longer than the panel ends with … 87 more — keep typing to filter, so filtering is always the way through a long list. Approval prompts are not a panel: they appear inline in the timeline and the composer waits for you. See Modes and permissions. Settings opens on categories, with / to search inside it. ↑/↓ or j/k navigate, g and G jump to top and bottom, Space or Enter toggles a row, → expands a submenu, d resets a row, and F2 or Esc closes. Appearance holds the display rows: Compact mode, Default screen mode, Show timestamps, Show thinking blocks, Group tool calls, Collapsed edit blocks, Line numbers, Word wrap, Syntax highlight, Animations and Theme. Themes are on Themes.

​
Alternate screen and small terminals

The TUI enters the alternate screen by default, which is why your shell scrollback is intact when you exit. Three ways to change that:
The Appearance row Default screen mode is the same setting in the UI, drawn as Fullscreen or Inline. The chrome holds its shape when the window is small: at roughly 40 columns by 12 rows the composer keeps its border, its chips and one footer hint, and the welcome copy switches to its narrow variant. Below that the layout has nothing left to fold. A ▼ marker appears in the timeline when there is more content below.

​
Usage and quota

A usage row names your plan and when it renews, in the pattern Usage · Cortex Pro · renews Oct 1. When the agent allowance is used up the row becomes × Agent quota exhausted and the composer holds new messages until it resets. Per-plan numbers are not published in the CLI itself; check your account for those.

​
Interrupt, quit, and failures

  • Esc interrupts the running turn. Esc twice in quick succession opens the rewind overlay, which steps back through the session or forks it. See CLI sessions.
  • Ctrl+Q or /quit quits. Ctrl+C force-quits.
  • If the coding service cannot be reached, the timeline says × The coding service is temporarily unavailable and invites you to try again in a moment. That is the whole message on purpose: the CLI does not surface provider, library or transport names. Your work so far stays in the session. See CLI troubleshooting.