stella chat

Start an interactive session. This is the default command: running stella with no subcommand does the same thing as running stella chat.

On a real terminal, stella chat opens the Command Deck, a tabbed terminal UI. Pass --accessible (or set STELLA_ACCESSIBLE=1) to run the same deck in a way a screen reader can read. Pass --plain (or set STELLA_PLAIN=1) for a plain line-based REPL instead. The deck also switches to plain mode automatically when stdin or stdout is not a terminal.

Synopsis

stella chat [global flags]

# Equivalent — chat is the default
stella [global flags]

# The same deck, drawn so a screen reader can read it
stella chat --accessible

# Plain line-based REPL instead of the deck
stella chat --plain

What it does

stella chat opens a conversation. You type a message, the agent runs its step loop (proposing tool calls, running them, and reading the results) until the turn is done, then hands the prompt back to you. The session keeps your conversation history across turns.

The default Command Deck shows the session as a set of tabs: SESSION (the transcript), AGENTS (executions and installed agents), TRACES, GRAPH, FILES, SKILLS, MCP, ISSUES (your connected GitHub or Linear tracker, with instant search), and SETTINGS (all config, including the engine-config panel). Slash commands jump between tabs and run actions, and ? opens a key list for the tab you're on. The plain REPL (--plain) is a single scrolling line-based loop with a smaller command set, good for narrow terminals and recordings.

Moving around

The deck is a tree: tabs, then the panes and lists inside each tab, then what a list item opens. Four keys walk it the same way at every level, starting from an empty prompt:

Esc does what ⌫ does, plus one more step: once there is nothing left to close, it interrupts the running turn (see below). Tab and Shift-Tab still cycle tabs. q or Esc closes any overlay, and ⇞ ⇟ Home End page through any list or body. With text in the prompt, the arrows edit it and ⌫ deletes, as you'd expect. The tree above is what the keys mean only when there is nothing to edit. ? lists every key for the tab you are on.

Off the SESSION tab, the row above the prompt is the pulse row. It shows which agent is working, its status, how long since it last did anything (it turns red once a running agent has been quiet for a minute and a half), where it is, and the last thing it said. This keeps every tab aware of the current turn.

Sub-agents

↓ on an empty prompt (or Ctrl-A, or /subagents) opens the SUB-AGENTS overlay. It lists every lane the lead dispatched and every delegate child running inside a turn, each with its quiet time, what it is for, and where it is. → or ⏎ opens a lane's transcript. The breadcrumb reads SESSION ▸ lead ▸ sub:2, and ⌫ brings you back to the lead. A prompt typed there steers that lane. Inside the overlay, n nudges the selected lane (a one-line "where are you?" that it answers on its own transcript), and f flags it to whoever dispatched it, with its status attached, asking them to check on it, stop it, or take the task over. ctrl-x ctrl-x kills it, p pauses or resumes it, r restarts it, and l returns to the lead. A delegate child has no control of its own: its row says so, ⏎ opens its parent, and f flags it to the parent.

Accessible mode

--accessible is a mode of the deck, not a smaller version of it. Every tab, gate, prompt queue, sub-agent, steering, and resume feature works the same. What changes is how the deck talks to your terminal.

• It never takes over the screen. The deck draws inline underneath your prompt instead of on a separate screen, so nothing is hidden and nothing disappears when you quit.
• Each completed message is written into your normal scrollback exactly once. It is announced as it arrives, reachable with your reader's review cursor, and still there after the session ends.
• Animation is frozen (as if --no-anim were set), so no part of the screen repaints on a timer.
• Panels stack in one column. The GRAPH and SKILLS tabs and the session's work rail all read top to bottom, so no row mixes two panes together.
• The grid views (TRACES, ISSUES, TOOLS, AGENTS, and INSTALLED) render as one labeled record per row (status running · cost $0.05 · cpu 3%) instead of lined-up columns, because column alignment is just whitespace to a screen reader.
• Moving around is announced. Switching tabs, opening or closing an overlay, and changing which agent has focus each say a line out loud.
• Messages the program itself speaks are marked ▸, so they are never mistaken for the model's own words.
• The terminal cursor stays on the real insertion point, which is also what an input method needs to place its candidate window.
• Mouse capture is forced off, so your terminal's own text selection keeps working.

If your terminal does not answer a cursor-position request, the deck still starts. It draws on your own screen without flushing to scrollback, and it says so instead of silently skipping that feature.

Set STELLA_ACCESSIBLE=1 in your shell profile to make this the default for every session.

The Accessibility page covers what each change is for, how the mode degrades on a terminal that won't answer a cursor-position request, and how to check the mode is working.

Typing while a turn is running

You never have to wait for a turn to finish. A plain prompt queues. It waits as the lead's next turn, behind anything already waiting, and the turn in progress is not touched. Press Esc and everything waiting (the queue, in order, plus whatever is in the composer) is delivered into the running turn at its next step, and the turn keeps going. A Steered line per message confirms it: nothing completes, nothing is canceled, and no second agent starts.

fix the flaky login test           ⏎   ← queued
also update the changelog          ⏎   ← queued behind it
                                   Esc ← both land in the running turn, in that order

Two prefixes skip the queue:

ui.mid_turn_prompt in settings changes what a plain prompt does while an agent is running: queue (the default above), ask (a card offers s steer / n next turn / p sidecar sub-session per prompt), spawn (every plain prompt forks a sidecar sub-session, dispatched alongside the running turn), or steer (the prompt lands inside the running turn at its next step boundary, and the chevron turns teal to say so).

Whatever the policy, Shift-Tab with a draft in the composer cycles the submission's intent by hand — gold dispatches, teal steers the running turn, red interrupts: a soft stop that keeps every completed step, with your words front-queued to run next. With an empty composer Shift-Tab keeps its usual job of cycling tabs.

Line breaks and soft-stop

A modified ⏎ (⌘⏎, ⌃⏎, or ⌥⏎) inserts a line break instead of submitting, and the break stays exactly as typed in the prompt. On a terminal that can't report the key combination, it falls back to a plain submit.

Pressing Esc with nothing queued and nothing typed pauses the current turn without ending the session. Esc Esc cancels it right away and holds the queue until your next message. See Agent engine paths for how steering works with each execution path.

Multimodal input

Prompts can include more than text. Mention a path to an image, PDF, audio, or video file in your message, and stella attaches the file itself as model input alongside your text. In the deck, Ctrl-V pastes an image straight from the clipboard as an attachment. See Multimodal input for the @-mention rules, what each provider can see, and how unsupported media is handled.

Flags

stella chat takes only the global flags. The ones that shape the chat surface:

Slash commands

The available commands depend on the surface.

Command Deck (default)

Open a tab or run an action:

Press Ctrl-C to quit the deck.

/info with an argument

/info also takes two arguments, and both run inside the deck without a model call. When the configured model is itself broken, /info refresh is how you fix it — routing it through a turn would fail on the very error you are trying to fix:

/info refresh           re-sync the catalog
/info refresh --force   re-download everything, ignoring ETags
/info list              the same listing the bare /info prints

Parsing here only looks for one recognized word (plus refresh --force). One word it doesn't recognize gets a usage message back rather than wasting a model call, and anything sentence-like after /info is treated as an ordinary prompt.

/profile — one setting for the whole session

/profile sets a model and a reasoning effort for every engine role at once, chosen from the models your API keys can reach:

/profile fast       cheapest models, thinking off, short replies
/profile balanced   good enough for daily work without spending too much
/profile pro        strong models, real deliberation, priority capacity
/profile ultra      the most capable models your keys can reach, effort at the highest setting
/profile auto       no profile — hand the choices back to the engine

Run /profile with no argument to see which profile your current settings match, what this session is running, and what each profile would pick right now.

How the models are chosen. stella's catalog doesn't track a capability tier, so a profile ranks the reachable models by list price. This is the same method auto_mode already uses to pick a verifier. It keeps the choice up to date as the catalog changes, but it's an approximation: a cheap frontier model ranks low until its price says otherwise. The confirmation message names every model it picked, so you can always see what you got. Models the catalog has no price for (gateway rows like openrouter/auto, which bill at whatever they route to) are left out of the ranking instead of treated as free.

The roles aren't tuned the same way. Triage stays below the worker in every profile, since it's a short classification with a time limit, and spending your best model on it doesn't help. Research sits at the same level as triage for a similar reason: it reads the code and reports what it found, and because it runs many times per question, a tier chosen for the worker would be paid for repeatedly. Neither research nor plan gets a model of its own; both use the worker's, so a later --model change moves all three together.

The verifier is trickier, because two goals pull against each other. A verifier from the same model family as the worker can share a blind spot and pass review twice, but a verifier well below the worker's tier can't follow the work it's grading and just approves everything. stella picks in the order that gives up the least. A model that is both independent and at least as capable wins outright. If nothing meets that bar but the strongest independent model is only one price rung down, independence is worth that one rung. Only when the best independent option is much further down does capability take over, and then the confirmation message says the review shares a family with the work.

What it changes, and what it leaves alone. A profile sets the model, effort, thinking switch, verbosity, and service tier for each role, saved to your user settings. It turns effort_auto, reasoning_auto, and auto_mode off, because those switches override per-agent effort settings — leaving them on would let /profile ultra claim max effort while actually running medium. Everything else stays as it was: custom per-agent prompts, pinned providers, temperatures, seeds, and your allowed_models list.

/profile auto undoes this. It turns all three switches back on and removes the per-role effort, thinking, verbosity, and service-tier settings a profile wrote, handing those choices back to the engine. Model pins stay as they are, since they may predate the profile, and auto_mode picks the verifier on its own again.

Effort, and providers that can't express it. The five-level scale is stella's own scale, not every provider's: Gemini and Vertex offer only low and high, the OpenAI models stop at high, and Z.ai has no per-request effort control at all (its thinking switch is just on or off). A choice whose provider can't match the level the profile asked for is set to the highest level that provider does support.

Just rounding down would flatten the scale. On a two-level provider, both fast and balanced would land on low. The missing level is recovered a different way: among models at the same price, the one whose provider can express the requested level wins. That's a tiebreaker, nothing more. The search never leaves the price range, so a profile can't overspend its tier to get a feature, and it picks the cheapest model that qualifies rather than the best one. Where nothing at that price can express the level, the rounding stands, and the confirmation message says which levels changed.

Like /model default, the change applies to sessions started from now on; the running session keeps its current model (a bare /model pick is the one that changes it right away).

Plain REPL (--plain)

The line REPL has a smaller, different set of commands. This is the whole list, and a /word outside this list is not a command there. Unlike the deck, which corrects an unrecognized bare /word, the REPL lets it through as an ordinary prompt, so a deck command typed here (/files, /diff, /graph, and so on) costs a model call and answers nothing.

Examples

Start a session with the default (auto-detected) model:

stella chat

Start a session by simply running the binary (chat is the default):

stella

Pin a model and cap session spend:

stella --model zai/glm-5.2 --spend-limit 5.00 chat

Run the deck with a screen reader:

stella chat --accessible

Use the plain line REPL (for example, for a narrow terminal, or a pipe):

stella chat --plain