Cap and track agent spend in Claude Code, Codex and Cursor
In short: To stop an unattended Claude Code run from burning money, use
claude -p --max-budget-usd <amount> (print mode only, a client-side estimate that can overshoot by about one
response) plus --max-turns. The dollar figure Claude Code shows is a list-price estimate;
modelPricing can restate it at your contracted rates, but only through managed settings, and it never
changes the bill. For everything else the real cap lives on the account side: usage-credit or workspace spend limits
for Claude, plan allowance, credits and the usage dashboard for Codex, on-demand and prepaid settings for Cursor.
Side by side
| Claude Code | Codex | Cursor | |
|---|---|---|---|
| Cap one run | --max-budget-usd and --max-turns (print mode only) | No dollar flag in the docs we checked; goals.max_goal_token_budget caps /goal tasks | No budget flag on the CLI parameters page |
| See spend | /usage, status line cost.total_cost_usd, total_cost_usd in JSON output | /status, /usage, usage dashboard | Dashboard (Spending tab on legacy plans, Usage page on newer plans) |
| Account-level cap | Usage-credit spend limit (Pro, Max, Ultra), Console workspace spend limits (API), org limits (Team, Enterprise) | Plan allowance; credits or usage-based billing extend it where your plan offers them | On-demand usage (legacy) or prepaid credit (newer plans) pays for more; without it you wait for the reset |
| Is the number your bill? | No, a local list-price estimate | Allowance usage depends on model, context and task, not a fixed price per message | Dashboard shows real-time usage for your plan |
Claude Code
Cap an unattended run: --max-budget-usd
This is the flag for scripts, cron jobs and CI. From the CLI reference: it stops the run once estimated spend on API
calls reaches the amount, and it is print mode only (-p).
claude -p --max-budget-usd 5.00 "your task"
claude -p --max-turns 20 --max-budget-usd 3.00 --output-format json "your task"
What the docs say about how it behaves, and what it means for the number you pick:
- It's an estimate. Claude Code checks the cap against its client-side cost estimate, which can differ from your bill.
- It can overshoot. The check runs after each model response arrives, because the cost comes from the token usage the API returns. The response that reaches the cap still completes and counts. Spend can pass the cap by up to the cost of that one response, plus whatever subagents still running at that moment spend before they stop. Set the cap below what you can afford to lose.
- Subagents count. Their spend goes toward the cap. Once the cap is reached, spawning another
subagent fails with
Budget limit reachedand Claude Code stops background subagents that are still running (that enforcement needs v2.1.217 or later). - Resumed totals don't count. With
--continueor--resume, the totals restored from earlier runs aren't counted against the cap, so each invocation gets its own budget. - Data residency pricing counts. A response billed at the 1.1× data residency rate is multiplied by 1.1 in the cost figure, and that multiplied figure counts toward the cap.
--max-turns is the other brake: it limits agentic turns (print mode only) and has no limit by default.
A budget limits estimated money and a turn limit limits loops, so set both. Our headless and CI article shows where these sit
in a full pipeline alongside timeouts.
Read the spend from a script
With --output-format json the response includes total_cost_usd and a per-model cost
breakdown, so a wrapper can log spend per run without opening a dashboard. If you drive Claude Code through the Agent
SDK instead, the result message carries a subtype: error_max_budget_usd means the run hit the budget before
finishing, and that result has no final text. Every result subtype, errors included, carries total_cost_usd,
so you can still record what a failed run cost. Both figures are client-side estimates.
What the dollar figure is, and what modelPricing changes
Run /usage and look at the Session block: Claude Code computes the dollar amount
locally from token counts at list price. The same total appears in the
status line's cost field, and the totals reset when
/clear starts a new session (since v2.1.211).
If your organization pays contracted rates, those figures won't match your bill. The managed setting
modelPricing fixes the reporting, not the charge. The docs describe it like this:
- Where it works: managed settings only (server-managed settings, an MDM policy,
managed-settings.jsonor a policy helper). Claude Code ignores it in user, project and local settings and in--settings. It needs v2.1.242 or later. If you are a solo developer, this setting isn't for you. - What you supply: a
multiplier(above 0, up to 10; below 1 is a discount, above 1 a markup, and a markup needs v2.1.271 or later), per-modeloverrideswithinput,output,cacheReadandcacheWritein USD per million tokens (all four required), or both. You enter the rates yourself; Claude Code doesn't read them from your contract or the Console. - What it affects:
/usage, the status line, the Agent SDK'stotal_cost_usd, the--max-budget-usdlimit, and the OpenTelemetry cost metric and events. So with a discount multiplier, a budget cap stops later than it would at list price. - How to confirm it's active: in a session that has received the managed settings,
/usageshows the noteat your organization's configured rateson the Total cost line.
{
"modelPricing": {
"multiplier": 0.85,
"overrides": {
"claude-sonnet-4-6": { "input": 2.4, "output": 12, "cacheRead": 0.24, "cacheWrite": 3 }
}
}
}
That is the docs' own example for managed-settings.json: contracted Sonnet 4.6 rates, with every figure
then reduced by 15%. Override rows are used exactly as written, with no fast-mode surcharge or US-only-inference rate
added on top.
If you're on a subscription, the cost number isn't your limit
The docs say the Session block is intended for API users: Pro, Max and Ultra usage is included in the subscription,
so the session cost isn't relevant for billing. What you can cap there is usage credits, the pay-as-you-go top-up
past your plan limit. /usage shows a usage-credits row (this month's spend against your monthly spend limit,
or Unlimited if you haven't set one), and /usage-credits opens the settings page where you turn
credits on or off and set the limit. On Team and Enterprise, admins set limits at the organization, group or member
level. On the Claude Console, set workspace spend limits. On Bedrock, Google Cloud or Microsoft Foundry, billing and
budgets live in your cloud provider's console.
A plan limit is a different thing from a spend cap. When a window runs out you wait or add credits; nothing is billed by the token. The status line article shows how to put the 5-hour and 7-day figures on screen.
Codex
Where the money comes from depends on how you sign in. The Codex pricing page says ChatGPT plans include a usage allowance shared by Codex and ChatGPT Work, eligible plans can extend it with credits or usage-based billing, and API-key sessions use separate API pricing rather than your ChatGPT allowance. The docs also say usage per task varies with model choice, context, reasoning, tool use and caching, so message counts are estimates, not fixed limits.
- Check usage in the session:
/statusshows session configuration and token usage./usageopens account token activity;/usage daily,/usage weeklyand/usage cumulativejump straight to a view. It needs an account sign-in, and the usage dashboard on your account has current limits and reset times. - Cap a long task:
/goalkeeps Codex working toward an objective, andgoals.max_goal_token_budgetinconfig.tomlsets the default token budget for new goals and the largest budget a goal can request. Leave it out and goals have no configured limit. - Per-run dollar cap: we couldn't find one in the Codex docs, so for an unattended Codex job rely on a
workflow timeout, a token budget on
/goaltasks, and the account-side limits above.
Cursor
Cursor's usage page splits it by plan type. On newer plans one weekly pool covers Cursor's own models, and third-party models are billed from prepaid credit on higher tiers. On legacy plans, included usage is split into a monthly Cursor Models pool and an Other Models pool, and the Spending tab in your dashboard shows real-time usage for both, remaining allowance and any on-demand charges. Unused usage doesn't roll over on either kind of plan.
- When you hit the limit: you get a notification in the editor. On newer plans you can keep working from prepaid credit, wait for the weekly reset or upgrade. On legacy plans you can enable on-demand (pay-as-you-go) usage or upgrade. If you do nothing, you wait for the reset.
- Your own API key: on individual plans those requests don't draw from your included usage or prepaid credit; your provider bills you directly, so the cap is whatever your provider lets you set.
- Per-run cap: the CLI parameters page lists no budget or spend flag. Model choice is the lever you have: Cursor says model selection affects how quickly included usage is used.
A practical setup
- Scripts and CI: always pass
--max-turnsand--max-budget-usdtoclaude -p, set the budget well below your limit, and logtotal_cost_usdfrom the JSON output. - Parallel agents: every session spends separately, and the cap applies per invocation, so ten agents with a 5.00 cap can spend about 50.00. Our parallel agents article covers running several at once; count them when you pick the number.
- Subagents: their spend counts toward a Claude Code cap, and a smaller model for helpers costs less. See custom subagents for choosing one per agent.
- Keep context small: Anthropic's cost docs trace unexpectedly high spend to long sessions that were never cleared, and to Opus left as the default model. The context window article covers compacting, and too many skills covers what loads every turn.
- Trust the dashboard over the CLI. Anything the CLI prints is a local estimate; your account's usage page or billing console is the authoritative figure.
FAQ
How do I set a spending limit for claude -p?
Add --max-budget-usd with an amount, for example claude -p --max-budget-usd 5.00 "your task". It works in print mode only and stops the run once estimated spend reaches the amount, including subagent spend. The check uses Claude Code's own cost estimate and runs after each response arrives, so the final spend can pass the cap by about one response. Leave headroom.
Does --max-budget-usd work in interactive Claude Code?
No. The docs list it as print mode only. In an interactive session, watch /usage or a status line cost field, and cap what you can pay at the account level: usage-credit spend limits on a subscription, or workspace spend limits in the Claude Console.
Is the cost Claude Code shows my real bill?
No. It is an estimate computed locally from token counts at list price. A managed modelPricing table can change it to your contracted rates, but the figure stays an estimate, and the setting changes what Claude Code reports, not what Anthropic charges. On a Pro, Max or Ultra plan, usage is included in the subscription, so the session cost is not what you pay.
Can I set modelPricing in my own settings.json?
No. modelPricing is a managed setting. Claude Code ignores it in user, project and local settings and in --settings. An administrator deploys it through server-managed settings, an MDM policy, managed-settings.json or a policy helper, and it needs Claude Code v2.1.242 or later.
Does Codex have a dollar cap like --max-budget-usd?
Not in the docs we checked. Codex usage on a ChatGPT plan comes out of your plan allowance, extended by credits where your plan allows, and API-key sessions are billed at API pricing instead. The closest built-in cap is goals.max_goal_token_budget, a token budget for /goal tasks. Check usage with /status, /usage and the usage dashboard.
Sources
- Claude Code docs: CLI reference (--max-budget-usd, --max-turns)
- Claude Code docs: Manage costs effectively (/usage, usage credits, modelPricing steps)
- Claude Code docs: Settings reference, modelPricing
- Claude Code docs: Run Claude Code programmatically (--output-format json)
- Claude Agent SDK docs: How the agent loop works (budget headroom, result subtypes)
- Claude Agent SDK docs: Track cost and usage
- Codex docs: Pricing (plan allowance, credits, API-key billing)
- Codex docs (ChatGPT Learn): Developer commands (/status, /usage, /goal)
- Codex docs (ChatGPT Learn): Configuration reference (goals.max_goal_token_budget)
- Cursor help: Usage and limits
- Cursor docs: CLI parameters