Work within a spend limit

You have a number in mind, and you don't want to find out you went over it afterward. Several mechanisms hold that ceiling. One of them fires before you spend anything at all.

The flag

stella --spend-limit 2.00 run "port the utils module to the new API"

--spend-limit is a global flag, so it can go on either side of the subcommand. Putting it first is a good habit, since it reads as a property of the whole command, which is what it is.

Set it once for a whole shell session or CI job instead:

export STELLA_SPEND_LIMIT=5

Where the run stops

This part is worth trusting, because it decides whether a stopped run leaves you with usable work or a mess.

Spend is checked between steps and stages, never in the middle of a tool call. So stopping a run never leaves a half-finished edit, a partly written file, or a tool whose changes happened but never got recorded. Work already saved to disk stays there. Nothing gets rolled back.

The exit code is 1, the same as any other failure. If you need to tell the spend limit stopped this apart from this just failed, read the JSON output:

stella --spend-limit 2.00 run --output-format json "…" | jq '{status, cost_usd, files_touched}'

The check that runs before you spend

A spend limit stops a run partway through. A scope review stops it before the first edit, which is usually what you actually wanted.

When a plan's size crosses any of three limits, stella pauses and shows you the plan:

Every check is a strict "greater than," so a plan that lands exactly on a limit passes without pausing. When it pauses, a approves the plan, t trims it down to the largest version that would not have triggered the pause, and x cancels it. Anything longer than one of those letters is read as what you want changed, and sends the plan back with your note attached.

A gate like this needs one rule to be useful in an unattended run: it must never approve itself automatically. With nobody there to answer, a plan that's over the limits should stop the run, not wave itself through — because a scope check that approves itself in CI isn't really a check. That's something to verify a plugin actually does. It isn't a setting this program controls, and no flag here turns it on or off.

What the money is actually spent on

Before you tune anything, know the shape of the bill. Most attempts to save money target the wrong stage.

Three things follow from that, and they're most of what you need to know:

1. The worker's model price dominates the bill. Switching the worker to a cheaper model changes the total by several times over. Switching the verifier barely moves it at all.
2. A top-tier verifier is cheap insurance. One verifier call is a few thousand input tokens and under a thousand output tokens. Keep it on a different model family than the worker.
3. --test-command is the strongest cost-saving flag on a wrapped run. It arms the plugin's built-in fail-then-pass check, so most runs finish on that evidence alone, skipping the verifier entirely — and it also skips the witness-writing call. It's not accepted on the raw loop, which never makes those calls in the first place.

# Cheapest correct shape when the result must carry evidence:
# the plugin's oracle armed, a hard ceiling on top.
stella --spend-limit 1.50 run --pipeline my-verifier \
  --test-command "cargo test -p api" "add cursor pagination to /orders"

The multipliers

A ceiling only helps if you know what's pushing against it.

When the conversation outgrows the window

A long run's cost isn't only what it does. It's also how much conversation it has to carry while doing it. When the conversation gets close to the compaction budget (150,000 tokens by default), stella shortens it and keeps going, instead of failing or silently cutting content.

Shortening happens in four steps, from least to most lossy:

1. Remove duplicates. If the exact same tool output appears more than once, only the earliest copy is kept — later copies just point back to it.
2. Remove outdated results. When the same call ran twice with the same input, only the newest result reflects the current state, so the older ones are stripped out as stale.
3. Trim old content. If it's still over budget, large old outputs get cut down to their beginning and end. The beginning keeps the tool's framing (a PASSED/FAILED line, file headers), and the end keeps the errors — so what's left is the part worth reading.
4. Drop content entirely. Only after that are the oldest large outputs replaced with a placeholder — and a result that's still the most recent one for its call is never dropped.

The system message and your latest message are never touched.

If a conversation is still over budget after all four steps, an overflow summarizer runs — a real, extra model call, recorded as --call-seq 1 for that step. Seeing these in stella inspect is the sign that a run's conversation, not its actual work, is what got expensive.

Picking the number

Set your spend limit from what you've actually seen, not a guess. Run the kind of task once with no limit, check what it cost, then set a ceiling with some room to spare:

stella run "the representative task"           # observed mode
stella stats --format text                    # what it actually cost
stella --spend-limit 2.00 run "the next one"   # now with a ceiling

The number worth tracking over time is cost per task solved, not the sticker price — a cheap model that needs three tries isn't actually cheap. The Observatory tracks this per model, and Examples & recipes has full setups at four different price points.

Next