Skip to content
BENIBIX Learn

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

AI⌨️ Claude Code

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

Example
Lucy's CI job asks Claude to fix lint errors. She sets --max-turns 10, so a run that cannot find a fix stops instead of using up the job's time.
Why it matters
A run with no end costs time and money. A cap puts a ceiling on both.
Full entry
AI⌨️ Claude Code

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

Example
Jack runs Claude over a hundred repos at night. Each run gets --max-budget-usd 2, so one repo that goes wrong cannot eat the whole night's budget.
Why it matters
Unattended runs can cost more than you expect. A cap puts a limit on each one.
Full entry

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.