Claude Code costs: see usage, keep context small, cap spend

Where the tokens go, the commands that keep a session cheap, and a hard cap for scheduled runs.

Claude Code bills by tokens, either against a subscription plan's limits or per token through an API key. Either way, a few habits decide whether a session stays cheap or quietly burns through your allowance. This guide shows how to see what a session costs, the three things that make it grow, and how to put a hard cap on unattended runs. Commands and flags are from Claude Code 2.1.x; check claude --help and /help on your version.

See what you are spending

Inside a session, /usage shows the session cost, your plan usage and what is contributing to your limits. /cost and /stats are aliases for the same command. Look at it after a long task, not only when a limit warning appears.

For a bounded non-interactive run, ask for JSON and read the cost from the result:

claude -p "summarize the failing tests" --output-format json | jq '.total_cost_usd'

The result object carries a total_cost_usd field, so a wrapper script can log what every scheduled run cost.

Why a session gets expensive

Keep the context small

Pick model and effort on purpose

/model sets the model and /effort sets the effort level for the session. On the command line the same are --model (an alias such as sonnet or opus, or a full model name) and --effort with one of low, medium, high, xhigh, max. A sensible default: a mid-sized model with medium effort for routine work, the larger one for planning and hard problems.

A hard cap for unattended runs

For jobs that run without you, --max-budget-usd sets the maximum amount to spend on API calls. It only works together with -p (print mode):

claude -p "run the nightly checks and report" \
  --max-budget-usd 2.00 \
  --output-format json

When the cap is reached the run stops and the JSON result reports a budget-exceeded error subtype instead of a normal result, so a wrapper should check the exit status and the result before treating the run as successful. Combine the cap with a narrow --allowedTools list; the cron and systemd guide shows the full setup.

A short checklist

The handbook covers running Claude Code on a server long term: sessions, alerts, backups and rules for what the agent may never do: Pocket Server.