Can you put a hard spending cap on an AI coding agent?

Not from the agent's command-line tool alone, if by a hard cap you mean a ceiling that can never be exceeded. As of October 30, 2026, Claude Code's documentation describes a --max-budget-usd option for print mode, based on a client-side cost estimate that can overshoot, and Codex CLI's command help and reference showed no hard monetary ceiling. Those are useful soft stops, not a promise of a maximum bill. The reason is structural rather than a missing feature: the cost of a model request is only known after the response comes back, so any limit checked by the client after the fact will overshoot by at least the last request. A real cap has to reserve the worst-case cost before each request is forwarded, at a point the agent cannot bypass. This page explains why, what such a cap requires and the practical limits you can set today. For the other limits an unattended run needs, see bounded autonomy.

What the CLI documentation said on October 30, 2026

Claude Code. The documentation as of October 30, 2026 describes a --max-budget-usd option. It applies in print mode, the non-interactive mode used for scripted runs. The budget is checked against a cost estimate computed by the client, and the total can overshoot the figure you set. When a session is resumed, spending from earlier sessions is not included in the total, so a resumed session effectively starts its budget again.

Codex CLI. No hard monetary ceiling was found in the Codex CLI's command help or reference at that time. Settings that control what an agent may do are not the same thing as a limit on what it may cost, so do not read a permission mode as a budget.

Vendor tools change quickly. Before you rely on either point, read the current documentation for the version you have installed, and look specifically for how the limit is measured, when it is checked and what happens on resume. A flag named 'budget' tells you the intent, not the enforcement.

Why a client-side budget is only an estimate

A client-side budget works like this: after each model response, the client adds up the tokens it was told about, multiplies by the per-token rates it knows and compares the running total with your limit. If the total is over, it stops before the next request.

Three things make that an estimate rather than a ceiling. First, the check happens after the cost is incurred. The request that crosses the line is already paid for, and a single large request (a big file read into context, a long generated output) can be a significant share of a small budget. Second, the rates and token counts are the client's view. If its rate table is out of date or some usage is not reported to it, the estimate drifts from what the provider records. Third, the budget is scoped to what the client can see: one process, and on resume not even the earlier sessions. Parallel agents, subagents in other processes and retries started by a wrapper script each have their own view.

None of this makes the flag useless. It stops a runaway loop in one process early. It just cannot promise a maximum.

What a hard cap actually requires

A hard cap has to act before the cost exists. The mechanism is a reservation. Before each request is forwarded to the model, something computes the worst case it could cost: the input tokens plus the maximum output tokens allowed, at current rates. If that worst case is more than the remaining budget, the request is refused. If not, the amount is reserved, the request is forwarded and, when the response arrives, the actual cost is settled and the unused part of the reservation is released.

Two conditions make this hard rather than soft. Every request must pass through the reserving component, so it must sit where the agent cannot route around it: on the provider's side, or in a trusted gateway that holds the real credentials while the agent only holds a key the gateway issued. And unknown usage must count as spent. If a response arrives without usage data, or a connection drops mid-response, the reservation stays in place, because unknown is not zero.

If your provider account offers a limit enforced on its side, read its documentation for how quickly it applies. Otherwise, a gateway is the only place a true cap can live.

Practical limits you can set today

Without a hard cap, combine limits that bound how much work can happen. Limit launches: a maximum number of agent processes per run. Limit time: a wall-clock limit per process, enforced by a supervisor that can stop it. Limit retries: usually one per task. Stop after consecutive failures, which is where runaway spend most often comes from. These do not measure money, but they bound the number and length of sessions, which is what drives it.

Use the soft budget too, where it exists. In Claude Code's print mode, setting --max-budget-usd below your real limit leaves headroom for overshoot. Avoid resuming a long session in an unattended run, since earlier spending is not counted.

Isolate unattended work. Run it under a separate account or API key from your interactive work, so its usage is visible on its own and any limit the provider applies to that account bounds it separately. Check the provider's own usage view the next morning rather than trusting a client total, and record per-run usage with gaps marked as unknown. See measuring agent token usage and when usage numbers are missing.

QUESTIONS

Does Claude Code's --max-budget-usd stop spending exactly at the limit?

According to the documentation as of October 30, 2026, no. It works in print mode and is based on a client-side cost estimate, so a run can overshoot the figure you set. Spending from earlier sessions is not included when a session is resumed. Treat it as a soft stop, set it below your real limit, and check the current documentation for your version.

Why does a hard budget need to reserve cost before each request?

Because the cost of a model request is only known after the response. A limit checked afterwards always lets the last request through, however large. Reserving the worst-case cost first, and refusing the request if the reservation does not fit, is the only way to make sure the total cannot pass the limit.

How do I limit what an unattended coding agent can spend overnight?

Combine limits on launches, time per process, retries and consecutive failures, which bound how much work happens. Add the CLI's soft budget where available, set below your real limit. Run unattended work under a separate account or key so its usage is isolated, and check the provider's own usage figures the next morning instead of a client estimate.

RELATED GUIDES

• How to read BRAIN FLUID reports and provenance

RELATED HARNESS PAGES

• Bounded autonomy: limits every unattended agent run needs Bounded autonomy: limits every unattended agent run needs, from an explicit task list to launch, retry, time, failure and spend limits.
• Measuring token usage of AI coding agents fairly Measuring token usage of AI coding agents fairly: whole-session ledgers, separate categories, deduplicated records, failed runs kept and unknown never zero.
• Why can't I see how many tokens my AI agent used? Token usage goes missing in interactive sessions, failed runs, uncounted cache categories and subagents. Why, and what to record instead of zero.
• agent run history and reports Agent run history and reports: what to record about AI agent runs, how to read usage coverage honestly and where unknown differs from zero.