Set a Spending Cap for Automated Runs with --max-budget-usd

Automated Claude Code runs can accumulate API costs quickly if a task is ambiguous or the model gets stuck in a loop. The --max-budget-usd flag sets a hard ceiling on how much a single run is allowed to spend.

# Stop after spending $2.00
claude -p --max-budget-usd 2.00 "Refactor the authentication module"

# Combine with --max-turns for double protection
claude -p --max-budget-usd 5.00 --max-turns 20 "Run the test suite and fix all failures"

When the budget is reached, Claude Code stops the run and exits. This flag only applies in print mode (-p), making it a natural guard for CI steps, scheduled scripts, and any automation where you need predictable costs.

The budget covers the full session, including all tool calls and model requests. Claude Code tracks the cumulative cost as it runs and stops proactively when the cap is hit rather than waiting for a hard API error.

Practical uses:

• Capping exploratory code-review tasks to a predictable amount per PR
• Protecting against unexpected token bloat when Claude reads unexpectedly large files
• Setting per-job budgets in GitHub Actions workflows

For interactive sessions, the /cost command shows current token usage but does not stop you from going over. For automated runs where you need hard limits, --max-budget-usd is the right tool.

# In a GitHub Actions step
claude -p --max-budget-usd 1.00 --output-format json "Review this PR for security issues" \
  || echo "::warning::Claude hit budget limit, manual review needed"

A budget cap is the only way to make Claude Code's cost in automation fully predictable.

via Claude Code CLI Reference