Headless claude -p has no turn limit by default; --max-budget-usd is the documented spend cap

Why this label: The source is the vendor's own CLI reference. We have not run these flags and cannot say how closely the estimate tracks real bills. Flags and version numbers change; check the current page.

Tried

Run Claude Code in print mode (claude -p) from a script or scheduled job without setting a turn or spend limit.

Broke

Documented behaviour rather than an incident: per the CLI reference, --max-turns has 'no limit by default', so an unattended run can keep going until the task ends or something else stops it. --max-budget-usd stops a run once estimated API spend reaches your amount, but the estimate is client-side and can differ from your bill, spend can pass the cap, and totals restored with --continue or --resume do not count toward it.

Cause

• confirmed Per the CLI reference, neither limit is on by default in print mode, and the budget check is based on Claude Code's own cost estimate.

“Confirmed” means the source states it as established; “suspected” means the source treats it as a theory or it is unsettled. We did not verify either ourselves.

Fix

From the docs: pass both flags, for example claude -p --max-turns 3 --max-budget-usd 5.00 "query". Spend from subagents counts toward the budget; once it is reached, spawning another subagent fails with 'Budget limit reached' and running background subagents are stopped. The documented enforcement needs Claude Code v2.1.217 or later. Leave headroom because spend can pass the cap.

Prevention

Put both flags in every scripted claude -p call, treat the budget as a ceiling rather than an exact bill, and also set a provider-side limit that does not depend on the client's estimate.

Sources

• Claude Code CLI reference (read 2026-10-27)
• HelloBuilder: Your Coding Agent Needs a Hard Budget Cap (2026-10-06)

← All stories