{"name":"--max-budget-usd","slug":"max-budget-usd","family":"cli","title":"CLI flags","noun":"CLI flag","description":"Maximum dollar amount to spend on API calls before stopping (print mode only). Spend from [subagents](\/docs\/en\/sub-agents) counts toward the cap. When you return to a conversation with `--continue` or `--resume`, totals [restored from earlier runs](\/docs\/en\/agent-sdk\/cost-tracking#accumulate-costs-across-multiple-calls) don't count toward it. Once spend reaches the cap, spawning another subagent fails with `Budget limit reached`, and Claude Code stops background subagents that are still running; the cap-enforcement behaviors require Claude Code v2.1.217 or later","description_source":"docs","described_by":{"doc":"claude-code\/cli-reference","title":"CLI reference"},"presence":{"first_seen":null,"removed_in":null,"in_current_build":false,"newest_mined":"2.1.308","builds":0,"mined_builds":149,"first_cited":{"version":"2.1.277","released_at":"2026-09-18 16:22:26","spans":1}},"aliases":[],"entries":[{"version":"2.1.299","anchor":"headless-run-host-with-max-turns-max-budget-usd-limits","heading":"Headless runs now say why they stopped, including when input ends","line":"Headless runs now end with a stated reason: the turn limit, the spending limit, or the host closing its input","released_at":"2026-10-14 00:23:19","reason":"found in this entry's text"},{"version":"2.1.295","anchor":"headless-session-adds-a-turn-and-budget-limiter","heading":"Non-interactive runs set up a new tracker for turn and spending limits","line":"When Claude Code runs without its interactive screen, it now builds a new tracker from the maximum-turns and maximum-budget limits","released_at":"2026-10-08 18:22:58","reason":"found in this entry's text"},{"version":"2.1.277","anchor":"print-max-budget-usd-halt-message-rewording","heading":"print --max-budget-usd halt message rewording","line":"Internal log wording for the --max-budget-usd halt now says 'this run's spend' instead of 'total cost'","released_at":"2026-09-18 16:22:26","reason":"found in this entry's text"},{"version":"2.1.277","anchor":"cli-budgettask-budget-argument-errors-now-thrown-as-a-diffe","heading":"CLI budget\/task-budget argument errors now thrown as a different error class","line":"Errors for invalid --max-budget-usd or --task-budget values now use a different internal error class, same message","released_at":"2026-09-18 16:22:26","reason":"found in this entry's text"},{"version":"2.1.246","anchor":"headless-runs-halt-at-the-spend-cap-and-stop-background-agen","heading":"Headless runs halt at the spend cap and stop background agents","line":"Headless runs now stop at your spend cap and shut down background agents instead of spending on.","released_at":"2026-08-25 19:17:34","reason":"named in this entry, found in this entry's text"},{"version":"2.1.242","anchor":"new-modelpricing-managed-setting-bills-usage-at-contracted-r","heading":"New modelPricing managed setting bills usage at contracted rates","line":"Organizations can bill your reported spend at contracted rates everywhere costs appear.","released_at":"2026-08-24 19:16:14","reason":"found in this entry's text"}],"entries_total":6,"docs":[{"source":"claude-code","path":"cli-reference","title":"CLI reference","documented":true},{"source":"claude-code","path":"changelog","title":"Claude Code changelog","documented":false},{"source":"claude-code","path":"costs","title":"Manage costs effectively","documented":false},{"source":"claude-code","path":"headless","title":"Run Claude Code programmatically","documented":false},{"source":"claude-code","path":"sessions","title":"Manage sessions","documented":false},{"source":"claude-code","path":"settings-reference","title":"All settings","documented":false},{"source":"claude-code","path":"whats-new\/2026-w30","title":"Week 30 \u00b7 July 20\u201324, 2026","documented":false}],"docs_total":7,"gates":[],"related":[{"name":"--max-cost-usd","slug":"max-cost-usd","description":"Help text for --max-cost-usd now explains its cost ceiling is checked before each run, not per single run"}],"url":"https:\/\/changelogs.core-directive.com\/reference\/cli\/max-budget-usd","family_url":"https:\/\/changelogs.core-directive.com\/reference\/cli.json"}