Guides
Step-by-step guides for real tasks — fix a red CI run, make a change in a codebase you don't know, find out what a run cost.
The rest of the documentation is organized around stella's parts: a page per command, a page per subsystem. This section is organized around your afternoon. Each guide walks through one real task from start to a checked result, in the order you would actually type the commands.
Nothing here repeats the reference pages. Every step links down to them, so you can go read the full details when you need them, and skip them when you don't.
Start here
CI is red on a branch you own. stella monitor watches it, fixes the root
cause, pushes the fix, and checks again. It stops only when the run is
green and anyone can see it. Covers what to do when the fix doesn't stick.
A list of small, separate fixes and one afternoon to do them. stella fleet runs them at the same time in one project folder, using file
claims to keep workers from stepping on each other. Covers how to split
up the list and how to check the results.
A codebase you have never read, and a change you have to make in it.
stella init builds a map of the code. stella search tells you what
else your change might break, before you write any code. Then you make
the change and check it.
A run cost more than you expected. Trace it from the total dollar amount
down to the exact model call that caused it, using stats, observe,
and inspect.
Set a hard dollar limit and see what stella does as it gets close to it: where it stops, what compacting the conversation costs, and how to spend money on the task instead of on chat history.
You have a product with an AI feature and a loop you built by hand. Swap in stella's loop and keep your own models, tools, keys, and data. Ends with a test that runs your whole agent loop without needing an API key.
Run stella and Claude Code side by side on the same set of tasks on every pull request. Block the merge only on loop correctness, which you can measure exactly. Report the quality difference separately, since that part is never exact.
Run Terminal-Bench 2.1 with stella and Claude Code in separate runs. Covers the setup, the checks that make the comparison fair, and the mistakes that quietly ruin a result.
Settings that won't apply, a key that won't resolve, a hook that never runs, a code map that answers about code you deleted. Four checks, in the order that finds the problem fastest.
What these assume
Every guide assumes you have installed stella
and that a provider key works. Run stella config — it should print a
provider, a model, and a partly hidden key, not an error. If it doesn't,
Getting started takes about thirty seconds, and this
page will still be here after.
Nothing else is assumed. If a guide needs gh, a git remote, or a code map
that's already built, it says so at that point, and tells you what happens
if you don't have it.
The idea behind every guide
stella's most important habit isn't any one command. It's that work only counts as done when there's proof, not just a claim from the worker. A test that failed before the change and passes after it. A diff that actually exists. A CI run that's green on its latest attempt. A different model checking the diff itself, instead of reading what the worker says it did.
Keep that in mind before you read the first guide. It explains a pattern you'll see again and again: the fastest, cheapest path is usually the one where you give stella something it can check on its own.
# --test-command arms an installed verification plugin's fail→pass flip oracle,
# which lets most runs finish on deterministic evidence and skip the verifier
# entirely. It is refused on the raw loop, which has no oracle to arm.
stella run --pipeline my-verifier --test-command "cargo test -p api" \
"add cursor pagination to /orders"The plugin socket explains all of this in full. You don't need it to follow any guide here.
Related reading
Complete settings.json files for a given set of keys and a given
budget. Answers how do I set stella up, where the guides answer how do
I get this done.
Deck, run, goal, monitor, fleet — which one to use, and why.
The reference every guide links into: each command's syntax, flags, and exit codes.
Repo initialization
What `stella init` builds — the domain taxonomy, the code graph, semantic search, extension adoption, and everything that lands under .stella/.
Fix a failing CI run
A branch is red. Walk it to green with stella monitor — what it does each round, what happens when a fix doesn't hold, and what "green" means here.