An agent that runs on its own stops when the task is done, not when your budget is. That’s fine for a quick question, but it’s a different story for a refactoring job in CI or a scheduled run overnight.
So, the question becomes: how do you put a ceiling on a Claude Code session?
Remark: Strictly speaking you can’t set a token limit. Claude Code caps on spend (tokens × price), so that’s what we’ll use.
The naive approach
Just run it and see what happens:
claude -p "Run the test suite, fix the failing tests in src/ and commit the fix"
There is no limit by default. Claude keeps going until it thinks it’s finished, and you find out the cost afterwards.
Two flags can help
Claude Code has two flags that act as a safety net in print mode (-p):
claude -p "Run the test suite, fix the failing tests in src/ and commit the fix" \
--max-budget-usd 3.00 \
--max-turns 30
--max-budget-usdstops the run once the estimated spend on API calls reaches the amount.--max-turnslimits the number of agentic turns. When the limit is reached, the run exits with an error, so your script can branch on the exit code.
I typically use both. A runaway loop that keeps retrying a failing fix hits the turn limit long before it gets expensive, and the budget flag covers the case where every turn is just very large.
Remark: The budget is a soft cap. It’s checked against a client-side estimate that can differ from your actual bill, and spend can pass the cap. Best to leave some headroom.
What about interactive sessions?
As far as I know, there is no equivalent hard cap for an interactive session. What you can do:
- Check the running cost with
/cost. - Look at what is filling your context window with
/context. - Use
/compactto summarize a long session, or/clearwhen you switch tasks. - When you’re billed through the API, set a spend limit on the workspace in the Anthropic Console as the backstop.
That’s it! Set both flags on every unattended run and treat the result as a safety net, not an exact meter.
