Skip to content
BENIBIX Learn

--max-budget-usd Flag

Also known as claude --max-budget-usd, Spend cap

It stops claude -p when the spend hits a dollar cap.

Think of it like

It is like you take five dollars to the fair. When it is gone, you go home.

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.

Definition

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

bash
claude -p --max-budget-usd 5 "Write tests for utils.py"
Stop once the estimate reaches five dollars.
--max-budget-usd is the second limit, in dollars.

Common mistake

Treating it as a hard wall. The last step can pass the cap, and the estimate is not your bill.

Key takeaways

  1. 1
    Dollars, estimated. Not the bill.
  2. 2
    Subagents count. Toward the cap.
  3. 3
    Leave room. It can pass it.

Compare

Learn it properly