Agent Modes

Stella has one engine and several ways to drive it. Pick the mode by how much autonomy you're delegating and how the work should be checked. (For the under-the-hood view — what each mode actually does differently inside the engine — see Agent Engine Paths.)

Interactive: the Command Deck

Running stella with no subcommand opens the Command Deck — a tabbed terminal UI over the same engine. Type to send a prompt; slash commands open tabs and overlays:

⏎ inserts a line break; ⌘⏎ / ⌃⏎ submits. Prompts queue while a turn runs — you never wait for the agent to finish before typing the next thing (Ctrl-T opens the queue editor). A !-prefixed line runs a shell command immediately in its own lane, skipping the queue. A single Esc cancels the in-flight turn; double-Esc cancels and holds dispatch so what you type next runs first. Prefer a plain line-based REPL? stella --plain (or STELLA_PLAIN=1).

Deck turns run the staged pipeline by default; /pipeline flips to the raw step loop.

One-shot: stella run

The non-interactive workhorse: one prompt in, verified work out, exit code back. Defaults to the staged pipeline; --test-command arms the deterministic fail→pass flip oracle; --no-pipeline selects the raw loop. Combine with --output-format json|stream-json and --budget for headless automation — see stella run and Scripting.

stella run "add a --json flag to the export command and update the tests" \
  --test-command "cargo test -p exporter"

Outcome-driven: goal mode

stella goal doesn't take a task — it takes an objective, and works in judged rounds until an independent judge (routed to a different model family than the worker whenever possible) confirms the objective is met from evidence. Each round is a full staged pipeline run by default (--no-pipeline for raw step-loop rounds). Backstops — a round cap, --budget, worker aborts — end the run honestly as "not met" rather than optimistically.

stella goal "the test suite passes and there are no clippy warnings"

Where stella run executes a single one-shot prompt, stella goal runs judged rounds. Each round the worker agent makes progress using the normal agent step loop, and then a separate judge model reviews the evidence and decides whether the objective has been satisfied. The loop ends when the judge confirms — or when a backstop trips: a hard round cap (default 8 rounds), the --budget limit, or a worker-turn abort. Reaching a backstop ends the run honestly, reporting the goal as not met with a named reason.

How judged rounds work

1. The worker works a round. The worker model runs the step loop — proposing tool calls, executing them, and feeding results back — to make progress toward the objective.
2. The judge assesses from evidence. The judge is not a passive transcript reader — it runs as its own bounded engine turn with read-only access to the same tools the worker used (read_file, grep, ci_status, and so on), actively inspecting the changed files, tests, and CI, and rejecting claimed-but-unproven success.
3. Repeat or finish. If the judge is not satisfied, another round begins — until the judge confirms or a backstop (round cap, budget, abort) ends the run.

Because the judge assesses from evidence rather than from the worker's narration, "I think I'm done" is never enough on its own — the goal is only considered met when the judge, looking at what actually happened, agrees.

Cross-family judging

The judge is routed cross-family — it deliberately runs on a different model family than the worker. Asking a model to grade its own work invites same-model bias: it tends to share the worker's blind spots and rubber-stamp its output. Routing the judge to a different family provides a genuinely independent second opinion.

Example

Give Stella a concrete objective and let it iterate until the judge signs off:

stella goal "Add input validation to the /signup endpoint and make sure the existing test suite passes"

Stella will work in rounds — editing code, running the tests, reading the output — and a cross-family judge will assess each round from the evidence. The run finishes only once the judge confirms the endpoint is validated and the test suite is green.

You can combine goal mode with global flags, for example pinning a specific worker model or capping spend:

stella --model anthropic/claude-fable-5 --budget 5.00 \
  goal "Migrate the config loader to the new settings schema and keep all tests green"

See Configuration and Telemetry for more on --model and --budget.

CI monitor: stella monitor

stella monitor is goal mode specialized for continuous integration. It watches CI for a branch or PR (default main) and keeps fixing failures until the pipeline is fully green.

stella monitor

Under the hood it uses the ci_status tool, and the goal is considered met only when the latest CI run is all-green — the same judged-loop discipline as goal mode, with "all CI checks pass" as the objective.

Parallel: fleets

When the work is many tasks rather than one, stella fleet fans a dependency-ordered task DAG out to parallel workers in one shared tree — cooperative file claims mean two agents never fight over the same file — with isolation = "isolated" opting a task into its own git worktree on its own branch.

Choosing

• You know the change and want to watch → the Command Deck.
• You know the change and don't need to watch → stella run (add --test-command for the strongest verification).
• You know the outcome but not the steps → stella goal.
• CI is red and you want it green → stella monitor.
• You have a backlog → stella fleet --plan.

Every mode shares the same tools, the same configuration, the same context engine, and the same local-only telemetry.