Home › Articles

Cap and track agent spend in Claude Code, Codex and Cursor

Updated 2026-11-19

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.

Checked against each vendor's docs on 19 November 2026. We did not run these commands inside a live Claude Code, Codex or Cursor session, so the flags and settings below are quoted from the docs, not from our own billing.

Side by side

Claude CodeCodexCursor
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 tasksNo 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 dashboardDashboard (Spending tab on legacy plans, Usage page on newer plans)
Account-level capUsage-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 themOn-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 estimateAllowance usage depends on model, context and task, not a fixed price per messageDashboard 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:

--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:

{
  "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.

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.

A practical setup

  1. Scripts and CI: always pass --max-turns and --max-budget-usd to claude -p, set the budget well below your limit, and log total_cost_usd from the JSON output.
  2. 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.
  3. 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.
  4. 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.
  5. 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

Official docs, checked 2026-11-19.

Get the free rules sampler + new tips by email

Confirm your email and we'll send you straight to the sampler download. Then one short email every two weeks covering tool format changes (Cursor, Claude Code, Codex, Windsurf, Copilot), new rules and kit updates. No spam.

We store only your email, with our email provider Resend. See the privacy policy.

Unsubscribe anytime from any email. Rather skip email? Get the sampler on GitHub or download the zip directly.