Claude Code Max Budget USD for Headless Runs
Prepared and checked using AI. Sources are linked in the article.
To set a spend cap for a Claude Code headless run, use claude -p --max-budget-usd 2.00 "your task". The flag stops a print-mode run when its estimated API-call spend reaches the amount. It includes subagent spend, but it is not an exact billing ceiling: the response that crosses the threshold can finish before Claude Code checks the total. Set the cap separately on every unattended invocation.
Set the cap on one run
For example, if auth.py is a file in your project and you want a bounded review, run:
claude -p \
--max-budget-usd 2.00 \
--max-turns 8 \
--output-format json \
"Review auth.py for correctness issues. Report findings with file locations. Do not edit files."-p runs Claude Code non-interactively, and --output-format json returns a structured result. The dollar amount is an example budget, not a recommendation for every task. Choose it from what you can afford for one attempt, allowing room for the response that may cross the threshold.
--max-turns 8 adds a separate limit on agentic turns. It can end a run before the dollar cap does; it does not reserve eight turns or predict their cost. For a task that needs several tool calls, a very small turn limit may stop useful work early. Start with a bounded task and adjust the two limits independently based on its results.
Use --output-format json when a scheduler needs to retain the result, session ID, and total_cost_usd. Claude Code exits with code 0 on success and a nonzero code when a run fails. Have the calling job retain both the exit status and output; a run that reached its budget should not be treated as a completed review or edit merely because it produced text.
Understand what the limit covers
The cap follows Claude Code’s estimated spend on API calls made by that run. It counts the main conversation and subagents the run starts. Once the limit is reached, Claude Code rejects another subagent spawn with Budget limit reached and stops background subagents still running. Those budget enforcement behaviors require Claude Code v2.1.217 or later, so check claude --version on machines where the limit matters.
| Activity | How to account for it |
|---|---|
| Main conversation | Its estimated API-call spend counts toward the run’s cap. |
| Subagents started by the run | Their estimated spend counts toward the same cap; they do not each receive a fresh allowance. |
A later claude -p invocation | Give it its own --max-budget-usd value. The previous invocation’s cap does not set a batch-wide limit. |
| A resumed conversation | Restored spend from earlier runs does not count toward the new invocation’s cap. Reported totals are cumulative only on supported versions when earlier totals were saved. |
| Commands and external services | Do not treat an API-call estimate as a limit on charges from services a command or integration may use. |
This distinction matters in a queue. If each item starts a new claude -p process with a $2 cap, the flag constrains each attempt’s estimate; it does not make $2 the ceiling for the entire queue. Your scheduler must decide how many items and retries to start. Record each result before launching a retry, especially when a task can repeatedly hit its cap without producing a usable change.
A resumed run needs the same care. You can use --resume or --continue with -p and pass a new cap, but the cap applies to the new run’s spend. On Claude Code v2.1.277 or later, the JSON total_cost_usd for a resumed conversation includes earlier runs’ spend when those totals were saved on normal process exit. To estimate what the latest invocation added, subtract the total recorded before resuming from the new cumulative total. Earlier versions reported each invocation separately, so add their totals instead; if the earlier process did not exit normally, do not assume its total was restored.
Leave room for the final API response
Claude Code learns a response’s cost from the usage returned with that response, then compares its running estimate with the cap. The response that reaches the threshold still completes. Spend may therefore exceed the specified amount by that response’s cost, plus spend by subagents that were still running while they stopped. There is no documented fixed overshoot amount to subtract from your budget.
If a job has a strict financial ceiling, set --max-budget-usd below that ceiling and use billing controls appropriate to the account as well. The needed headroom depends on the work: a short, focused request offers different exposure from a request that reads a large context, generates a long answer, or runs subagents concurrently. Keep the task narrow enough that stopping at the cap leaves an understandable partial result.
The limit also does not measure elapsed time or guarantee task completion. A run can stop because it reaches --max-turns, encounters an error, or finishes its assigned task before spending the budget. Decide what a usable result looks like before automating retries. For a review, require the expected findings format; for an edit, inspect the diff and run the project’s checks before accepting it.
Read the estimate without mistaking it for a bill
The JSON result’s total_cost_usd is a client-side estimate computed from usage and pricing information. It can differ from actual charges when prices change, a client version does not recognize a model, or billing rules differ from the client’s calculation. Retain the estimate for run-level monitoring, and use the Claude Console’s usage information for authoritative API billing.
This difference is especially important when Claude Code is authenticated through a subscription. Pro and Max usage is included in the subscription, so a session’s dollar estimate is not its billing amount. Read --max-budget-usd as a limit on Claude Code’s estimated API-equivalent consumption for the run, not as a promise that the account will be charged that many dollars. Account or workspace spend limits serve a different scope from this per-run flag.
For a batch, store a record for each invocation: the task identifier, cap supplied, exit status, JSON result, and whether the output meets your acceptance criteria. Sum independent runs’ estimates for an operational view, while keeping billing reconciliation separate. For resumed conversations, use cumulative totals only when the client supports them and the earlier process exited normally; otherwise, account from the separately recorded results.
Keep unattended permissions explicit
A budget cap controls estimated model spend; it does not decide which files Claude may edit or which commands it may execute. For an unattended review that should only read files, give the task a clear scope and restrict its tools. For example:
claude -p \
--max-budget-usd 2.00 \
--max-turns 8 \
--tools "Read" \
--permission-prompts none \
--output-format json \
"Review auth.py and report correctness issues. Do not edit files."--tools "Read" restricts the built-in tools available for this example. It does not restrict MCP tools; if those are configured, use the relevant deny rules or control the MCP configuration separately. --permission-prompts none denies requests that permission rules, permission modes, and PermissionRequest hooks have not resolved, and tells Claude not to retry them. An ordinary -p run without a permission host already denies unanswered requests; the flag prevents waiting when an SDK permission host or permission-prompt tool would otherwise handle them. That flag requires Claude Code v2.1.259 or later.
For repeatable scripted calls, --bare can reduce automatically loaded hooks, plugins, MCP servers, memory, and project instructions. It also changes authentication: bare mode does not use a subscription login or system keychain, so an Anthropic API run needs an API key supplied through the environment or an appropriate key helper. Choose it deliberately for the environment running the job.
If several coding tasks run at once, give every invocation its own cap and track their combined estimates in the orchestrator. Separate working copies help keep file changes from colliding, but worktree isolation does not combine or enforce dollar budgets. For broader planning, see what parallel agent runs cost and how to detect when a headless agent finishes.
Where Parallel Code fits
Parallel Code is our free, open-source desktop app for macOS and Linux. It runs several AI coding agents, including Claude Code, in parallel, each in its own git worktree, and provides a diff-first review surface. Apply Claude Code’s per-run budget flag to any unattended Claude Code invocation you launch; Parallel Code’s worktree isolation addresses concurrent file changes, while the flag addresses that invocation’s estimated API spend.
Frequently asked questions
Is --max-budget-usd a hard billing cap?
No. Claude Code checks its client-side estimate after an API response arrives, so the final response and still-running subagents can take the estimate past the specified amount. The estimate can also differ from the bill; use account billing controls when you need an account-wide limit.
Does a subagent get its own budget?
No. Spend by subagents started within the run counts toward the same cap as the main conversation. When the cap is reached, new subagent spawns fail and running background subagents are stopped on versions with the documented enforcement behavior.
Does the cap carry over when I resume a session?
No. Pass --max-budget-usd again for the resumed claude -p invocation; restored spend from earlier runs does not count against its new cap. On v2.1.277 or later, its JSON total_cost_usd includes earlier estimated spend saved on normal process exit; earlier versions reported each invocation separately, and an interrupted exit may leave earlier totals unrestored.
Can I set one cap for an entire batch of runs?
The flag applies to an individual print-mode run. Set it on each invocation, then have the batch scheduler track combined estimates and decide whether to start another task or retry.