--max-turns vs --max-budget-usd
People think --max-turns and --max-budget-usd are two ways to set the same limit. They count different things. --max-turns counts rounds: each time Claude acts and reads the result is one turn. --max-budget-usd counts dollars, using Claude Code's own estimate. A run with few turns can still cost a lot if each turn reads big files. A cheap run can still take many turns. Set both on unattended runs.
--max-turns Flag
It caps how many turns claude -p may take.
--max-turns sets how many turns claude -p may take before it stops. A turn is one round where Claude acts, such as running a tool, then reads what came back. There is no limit unless you set one. It keeps a run that is stuck from going round and round.
--max-budget-usd Flag
It stops claude -p when the spend hits a dollar cap.
--max-budget-usd stops claude -p once the spend reaches a dollar amount you set. The spend is Claude Code's own estimate, so it can differ from your bill. Spend by subagents counts too. A step that is already running can take the total past the cap, so leave some room.
In one line
- --max-turns Flag
- It caps how many turns claude -p may take.
- --max-budget-usd Flag
- It stops claude -p when the spend hits a dollar cap.