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.
Log in to leave a comment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.