How to Put Claude Code on a Token Budget

There's a category of feature that never gets a tutorial because it's one line long. This is one of those. Everyone making Claude Code videos covers the multi-agent workflow stuff — the part where your prompt fans out into a small fleet of agents that review, verify, and argue with each other. Almost nobody covers the knob that decides how big that fleet gets.

The knob is a suffix. You type your prompt, and at the end you add a budget:

audit the checkout flow for race conditions +2M

That +2M is the whole feature. It hands the orchestration a hard ceiling of two million tokens, and everything downstream sizes itself to fit.

Why "hard ceiling" is the interesting part

Most cost controls in AI tooling are suggestions. This one isn't. Once the budget is spent, further agent spawns fail — the workflow physically cannot overspend you. And the workflows are written to pace themselves against it. The internal loops literally look like this:

while (budget.total && budget.remaining() > 50_000) {
  await agent("find more bugs")
}

Keep hunting while there's at least 50,000 tokens left in the tank; stop when there isn't. Give it a small budget and you get a tight, focused pass. Give it a big one and it keeps going — spawning more finders, more verifiers, more rounds — until either the work is done or the money runs out.

The other half of the sizing logic is a rule of thumb baked into the scripts: roughly one substantial agent per 100,000 tokens. That's the entire mental model. +1M is about a ten-agent operation. +250k is two or three agents. You now know how to size a fleet.

The grid: what each level buys

These fleet counts are approximations from that 100k-per-agent heuristic, not a spec — but they've held up well in practice.

Budget	Fleet	What it buys
(none)	default	Unmetered. The workflow falls back to a default scale and its own judgment. Fine for everyday work.
+100k	~1–2 agents	A second opinion. One focused reviewer plus one skeptic trying to refute its top finding.
+250k	~2–4 agents	A review with receipts. Two or three dimensions — bugs, performance, tests — checked in parallel, top findings verified.
+500k	~5–8 agents	The sweet spot. The full pipeline: findings fan out, and each one gets an adversarial verifier whose job is to kill it before it reaches you.
+1M	~10–15 agents	An audit, not a review. Discovery loops that keep spawning finders until rounds come back empty.
+2M	~20–30 agents	Overnight-quality work in one run. Finder pools, three-vote verification panels, and a critic whose only job is asking "what's missing?"
+5M	~50+ agents	"Be comprehensive" as a loop condition. Multi-round sweeps that only stop when two consecutive rounds surface nothing new.

Same tokens, different bill

Here's the wrinkle that makes this worth a whole post instead of a tweet: the ceiling is counted in tokens, not dollars. A token debits the budget equally whichever model produced it — but what that token costs you varies a lot by model. At Anthropic's standard API list rates as of August 2026, a fully spent +1M budget of output tokens runs roughly:

Model	Output rate	A spent +1M costs about
Claude Haiku 4.5	$5 / 1M tokens	$5
Claude Sonnet 5	$10 / 1M tokens	$10
Claude Opus 4.8	$25 / 1M tokens	$25
Claude Opus 5	$25 / 1M tokens	$25
Claude Fable 5	$50 / 1M tokens	$50

Same ceiling, ten-times spread. (If you're on a Pro or Max subscription rather than paying per token, this shows up as a bigger or smaller bite of your usage allowance instead of an invoice — the ratios are what matter.)

Two practical consequences fall out of that table.

On an expensive model, cap harder. If you're running Claude Fable 5 — the $50-per-million tier — an unmetered exploratory prompt is how you wake up to a surprising bill. The budget directive is the fix, and it costs you one suffix:

review this diff, verify the top findings +150k

A lean ceiling on a premium model forces a tight two-agent pass instead of a leisurely wander. You still get the frontier-model judgment; you just don't pay for frontier-model meandering.

Mix models inside one budget. Workflow agents inherit your session's model by default, but each agent can be assigned a different one. The pro move at any given ceiling is cheap agents for the mechanical sweep and expensive ones only where judgment matters:

audit auth — haiku agents sweep, fable verifies survivors +500k

One quirk worth knowing: because every token debits the ceiling equally, mixing models stretches your dollars, not your token budget. A Haiku token and a Fable token are the same size to the meter. The savings show up on the bill, not in headroom.

Where we actually use this

The place this earns its keep for us is directory builds. A programmatic directory site means the same operation repeated across hundreds of pages — generation, validation, schema checks — which is exactly the shape of work that multi-agent workflows eat for breakfast and exactly the shape that can quietly burn tokens if you let it free-run. Budgeted prompts turned "hope this doesn't cost much" into "this run costs at most X," which is the kind of boring predictability we consider a feature. If you're building one yourself, our directory website guide covers the whole stack, and Directory Stack is the packaged version of everything we learned doing it.

And if reading about token ceilings and agent fleets made your eyes glaze — fair. That's roughly the entire pitch for having someone else run your website so you never have to think about any of this.

FAQ

What is a token budget directive in Claude Code?

A token budget directive is a suffix like +500k or +2M appended to the end of a Claude Code prompt. It gives the prompt's multi-agent orchestration a hard ceiling measured in tokens. Workflows scale their thoroughness to the ceiling — smaller budgets produce fewer, more focused agents, and larger budgets allow deeper multi-round work — and once the budget is spent, further agent spawns fail rather than overspending.

Is the budget a hard limit or a suggestion?

It is a hard limit. The orchestration tracks tokens spent across the whole run in one shared pool, and when spending reaches the ceiling, additional agent calls fail. Workflow loops are written to check remaining budget and wind down gracefully before hitting it.

Does the same budget cost the same on every model?

No. The budget is denominated in tokens, and every model's tokens count equally against it, but the price per token differs by model. At Anthropic's published API rates as of August 2026, one million output tokens costs about $5 on Claude Haiku 4.5 and about $50 on Claude Fable 5 — a ten-fold spread for the identical ceiling. Subscription users see the difference as usage-allowance consumption rather than a per-token bill.

How big a budget should I use?

A rough rule of thumb: about one substantial agent per 100,000 tokens. Use around +100k to +250k for a focused review, +500k for a full find-and-verify pipeline, and +1M or more for audit-scale work where discovery loops keep running until they stop finding new issues. On expensive models, lean smaller; the ceiling forces focus without reducing the model's capability.