A token budget is a decision about what happens at the limit, not a number. What to meter, what window to meter it over, the difference between a cap that stops work and a cap that only warns, and why the run you did not start is the only one you can honestly stop.
what a budget actually is
A token budget is a rule of the shape: this much of this measure, over this window, and this happens when it is reached. All four parts are load bearing. A number with no window attached cannot be exceeded, because there is no interval over which to exceed it. A number with no consequence attached is not a budget, it is a reading on a dial. And a measure you have not defined precisely is the most common failure of the four, because tokens are not one substance and pricing them as though they were is how people arrive at a figure that is off by a multiple.
This matters more with several agents than with one. A single agent in a terminal spends at roughly the rate you can read, because it spends most of its time waiting for you. Four agents working unattended spend at four times a rate you are not watching. The point of a budget is not frugality. It is that unattended work needs a number that can be checked without you, and a decision about the limit made while you were calm rather than while you were staring at an invoice.
the four things you meter, and why they must stay apart
A coding agent's usage arrives in four classes, and every serious rate card prices them differently:
- Fresh input. Tokens the model has not seen before in this conversation: the prompt you typed, the file it just read, the tool result it just received.
- Cache writes. Tokens being stored so a later turn does not have to resend them. These cost more than fresh input, which surprises people, and there is usually more than one cache duration at more than one price.
- Cache reads. Tokens served out of that cache on a later turn. These are the cheap ones by a wide margin.
- Output. Tokens the model generates. Almost always the most expensive class per token, and almost always the smallest count.
Keep them apart because their proportions in agent work are extreme. A long coding session re-sends the same repository context turn after turn, so the great majority of tokens flowing through it are cache reads. Our measurement across a large pile of real transcripts is in what Claude Code actually costs: cache reads dominate the count so thoroughly that summing all four classes and pricing them at the input rate is not a rounding error, it is a different answer.
On Anthropic's published rate card, read on 2026-08-07 and subject to change, cache reads are priced at a small fraction of the base input rate while cache writes sit above it. Check the current card rather than trusting that sentence; the point that survives any repricing is structural, which is that one blended token count cannot be converted into money. If you are building the arithmetic yourself, the cost of a context window works through what one full window costs per turn in each of the three input states.
choosing the window
The window is the part people skip, and skipping it produces budgets that cannot fire.
Per turn is too small
A cap on a single request stops nothing that matters. The runaway case is not one enormous turn, it is two hundred ordinary turns while you were at lunch. Per-turn caps are a safeguard against a pathological prompt, which is a real but rare failure.
Per month is too large
A monthly figure tells you what happened after it has happened. By the time a month-scale number moves visibly, the afternoon that caused it is over. Monthly budgets are an accounting instrument, and the monthly arithmetic is worth doing, but it is not a control.
A rolling window of hours is the useful one
Something in the range of one to a few hours matches the unit of work people actually perform: a session, an afternoon, one attempt at a feature. It is long enough that a single expensive turn does not trip it and short enough that a fleet burning money at four times your expectation announces itself before you have finished the thing you walked away to do.
One implementation detail catches everyone who builds this. If you keep a list of active runs and prune finished ones after a few minutes, you cannot compute a multi-hour window by summing that list. The list forgets faster than the window remembers. The window has to be fed as a running total, updated the moment usage is observed and persisted somewhere that survives a restart, or it silently reports only the last few minutes and reports them as though they were hours.
# what a window record needs, at minimum
observed_at timestamp
agent_id which node spent it
origin started | observed (see below, this one decides caps)
input fresh input tokens
cache_write cache creation tokens
cache_read cache read tokens
output output tokens
model because the rate card is per modelwarn, or stop
Now the part that is a design decision rather than arithmetic. When the threshold is crossed, something has to happen, and there are only two honest options.
A warning changes a colour, raises a notification, and leaves the work running. It costs nothing when it is wrong. Its weakness is obvious: a warning nobody sees is indistinguishable from no budget at all, which is why the readout has to be somewhere you are already looking rather than behind a panel you have to think to open.
A stop actually ends work. It is the only thing that bounds spend, and it has a real cost, which is that an agent killed mid-edit does not leave a tidy stopping point. It leaves a file half rewritten, a test suite in an unknown state, and a branch whose diff you now have to read as forensics rather than as review. If each agent is in its own git worktree, and it should be, the damage is at least contained to one branch. It is still damage.
the run you did not start is the one you may not stop
Here is the rule that makes the previous section decidable, and it is a rule about consent rather than about tokens.
A meter worth having watches everything, not just the work launched through its own button. If it only counts the runs a human explicitly started, it counts almost nothing: people open an agent and type into it, and that is where the money goes. So the meter has to open a record whenever an agent goes to work, however the work began. Call that an observed run. Call work a human deliberately launched under a cap a started run.
The distinction is not bookkeeping. It is the difference between a safety feature and a feature that destroys your work without being asked. Nobody consented to the observed run being governed. The user typed into a terminal; they did not opt into a threshold that would kill their editor mid-sentence. Metering it is fair, because counting money that is being spent harms nobody. Gating it is not, because the consequence lands on work the person never submitted to the rule.
Coverage first, then precision. A meter that sees all the spending and gates only the fraction that opted in is strictly more useful than a meter that gates everything it sees and sees almost nothing. Skribbl implements exactly this split, and it is written down as a promise to the user rather than as an implementation detail, precisely so that a later change cannot quietly widen what is allowed to be killed.
The same reasoning generalises. Any automatic control over an agent needs an answer to "who agreed to this," which is the same question that governs which agent may instruct which. In both cases the safe default is that authority is authored explicitly, never inferred from the fact that the system happened to be watching.
whose budget is it
A single total across a fleet is the wrong shape, for the same reason a single total across a team is the wrong shape. It tells you that something is expensive and not which thing, and the action you want to take is always against one agent.
Keep the running total per agent and sort by burn rate rather than by cumulative spend. Cumulative spend ranks the agent that has been running longest; burn rate ranks the agent that is currently going wrong, which is the one you want at the top of the list. Then make the row itself actionable. A number you cannot act on from where you are reading it sends you hunting for the right terminal, and that hunt is the reason people stop checking.
Above the per-agent rows, one combined figure is worth having, and its units depend on how the agents authenticate:
Showing dollars to a subscription user is showing them a number that is notionally interesting and practically zero, while the thing they actually fear, hitting the wall mid-afternoon, goes unmeasured. Headroom is the scarce resource on a subscription. Money is the scarce resource on an API key. Meter the one that is scarce.
picking the number
There is no defensible universal figure here and anyone who gives you one is guessing. What there is, is a procedure.
- Run without a cap first, with the meter on. One week of your own actual work, observed. You cannot set a threshold on a distribution you have never seen, and your guess will be wrong in a direction you cannot predict.
- Set the threshold above your normal peak, not at your average. A budget that fires on ordinary days trains you to ignore it, and an ignored budget is worse than no budget because it feels like coverage.
- Make the first threshold a warning. Live with it for a while. Note every time it fired and whether you would have wanted the work stopped. Most people find the answer is no more often than they expected.
- Add a stop only where recovery is cheap. Deliberately launched batch work in an isolated worktree, yes. Whatever you are typing into right now, no.
One more thing, not about the number at all. The most effective spend control in multi-agent work is not a cap, it is a visible running total you did not have to ask for. Most overspend is not a runaway loop; it is four agents quietly doing slightly more work than you assumed for slightly longer than you meant, and a figure in front of you fixes that long before any threshold is near. That is also the argument in why multi-agent coding fails for treating unwatched spend as structural rather than a discipline problem.
common questions
How do you limit what an AI coding agent spends?
You meter the agent against a window, set a threshold on that window, and decide in advance whether crossing it warns you or stops the work. The decision at the threshold is the budget; the number is only the trigger. Concretely: a running total per agent that survives a restart, a rolling window measured in hours, and one place the total is visible without you asking.
What is a token budget?
A token budget is a rule of the form: this much of this measure, over this window, and this happens at the limit. A number with no window and no consequence attached is not a budget, it is a reading. The measure can be tokens, dollars or percentage of a rate-limit window, and which one is right depends on how your agents authenticate.
Should a token budget stop an agent in the middle of a task?
Only if a human deliberately launched that work under that cap. Killing an agent mid-edit leaves a half-written file and a branch nobody can trust, so work a meter merely observed should warn and never gate. The distinction is consent: counting harms nobody, while terminating applies a consequence to a person who never agreed to the rule.
Do you budget in tokens or in dollars?
It depends on how the agent authenticates. On a subscription the marginal cost of a turn is zero and the scarce thing is rate-limit headroom, so budget in headroom and show time to reset. On an API key the scarce thing is money, so budget in dollars. Showing live dollars to a subscription user displays a number that sits near zero while the limit they actually care about goes unwatched.
Why can you not add up an agent's tokens and multiply by one rate?
Because fresh input, cache writes, cache reads and output are billed at different rates, and in a long coding session most tokens are cache reads. Blending them into one count and pricing it at the input rate is wrong by a large multiple. A budget denominated in money has to carry the four classes separately from the point of measurement, because they cannot be separated again afterwards.
If you want the arithmetic rather than the concepts, the two measurement posts are what agents cost per month and the cost of a context window. If you want to see what an always-on meter looks like in a tool that keeps the four classes apart, the docs describe how Skribbl reports it, and the pricing page says what the app itself costs, which is separate from and much smaller than what your agents cost.