Headless Notes

Claude Code: How to See Token Usage (and Reduce It)

By Headless Notes · Published · 10 min read

To see token usage in Claude Code, type /usage in an interactive session. The Session block lists your input, output and cache tokens per model, plus an estimated dollar total (Claude Code docs: Manage costs). For headless runs, add --output-format json to claude -p. The result then includes total_cost_usd and a cost breakdown per model, so a script can log every run (Run Claude Code programmatically). For the real bill on an API key, check the Usage page in the Claude Console. Claude Code's own figures are client-side estimates.

Which option is right for you?

The right place to check depends on how you pay and whether anyone watches the run.

Your situationWhat to pick firstFirst page to open
Beginner, interactive sessions only/usage inside Claude CodeManage costs
Daily work on a Pro/Max subscription/usage plan bars plus the 24h/7d breakdownManage costs → Plan usage breakdown
Recurring headless jobs (cron, CI)--output-format json + --max-budget-usdRun Claude Code programmatically
Tight budget on an API keyWorkspace Spend limits in the ConsoleWorkspaces
Want numbers for a dashboardUsage and Cost Admin API or OpenTelemetryUsage and Cost API

How to read /usage (and where /cost went)

/usage is the in-session command for token and cost numbers. Current docs describe everything under it.

The changelog still names /cost in recent entries, such as the v2.1.296 note about cache-read pricing (changelog). If /cost doesn't do what an older tutorial says, use /usage.

Steps

  1. Start a session with claude and do some work.
  2. Type /usage and press Enter. It runs right away, even while Claude is responding (Commands).
  3. Read the Session block: Total cost, Total duration (API), Total duration (wall), Total code changes, and Usage by model. Usage by model shows input, output, cache-read and cache-write tokens for each model (Manage costs).
  4. On v2.1.251 or later, check the Prompt cache (main) line. It shows the share of input tokens that came from cache and the number of cache misses. A high miss count usually means you paid full price to re-read context.
  5. On a Pro, Max, Team or Enterprise plan, scroll to the breakdown. It shows usage split across skills, subagents, plugins and MCP servers, and flags any behavior that accounts for 10% or more of recent usage. Press d or w to switch between 24 hours and 7 days.

What the numbers mean

Common mistakes and fixes

How to track token burn in headless runs

For unattended work, ask for JSON output on every claude -p call and keep a log of total_cost_usd.

Steps

  1. Add --output-format json:

``bash claude -p "Summarize open TODOs in src/" --output-format json | jq '.total_cost_usd' ` The payload contains result, session_id, total_cost_usd` and a per-model cost breakdown (headless docs).

  1. Add a hard stop with --max-budget-usd 5.00. The run stops once estimated spend reaches the cap, and spend from subagents counts toward it. Spend can go past the cap, so leave some headroom (CLI reference).
  2. Add --max-turns to stop runaway loops. When the limit is hit, the run exits with an error.
  3. In CI, add --bare. It skips loading hooks, plugins, MCP servers and CLAUDE.md, which keeps startup context small and predictable. Bare mode does not use your subscription login, so set ANTHROPIC_API_KEY (headless docs).

Example: a cost-logging wrapper

This is an illustrative script, not an official tool. Change the paths and limits to suit your setup.

#!/usr/bin/env bash
# run-claude.sh "<prompt>"
ALERT_AT=2.00
out=$(claude -p "$1" --output-format json --max-budget-usd 3.00 --max-turns 30) || status=$?
cost=$(echo "$out" | jq -r '.total_cost_usd // 0')
sid=$(echo "$out" | jq -r '.session_id // "none"')
echo "$(date -u +%FT%TZ),$sid,$cost,${status:-0}" >> "$HOME/claude-costs.csv"
if (( $(echo "$cost > $ALERT_AT" | bc -l) )); then
  echo "Claude run $sid cost \$$cost (alert at \$$ALERT_AT)" >&2
  # send to a channel you own, e.g. curl -X POST "$YOUR_WEBHOOK_URL" -d "..."
fi

The script still logs when the run fails, because || status=$? stops a non-zero exit from killing it. Failed runs still use tokens, and the SDK docs note that error results carry cost too (Track cost and usage). To schedule the script, see Claude Code Cron Job Setup: Run Automations Overnight. If runs stop early because of --max-turns, read Why Claude Code Stops Mid-Automation (and How to Fix It).

Common mistakes and fixes

How to wire usage checks into hooks

Hooks are good for cutting tokens, but they can't produce a per-run cost alert on their own. According to the hooks reference, Stop and SessionEnd hooks receive session_id, transcript_path, cwd and a reason, but no token or cost data.

What does work:

  1. Alerting: put the cost check in the wrapper script above, which runs after the -p process exits. The cost figure exists there and nowhere else.
  2. Resume warnings: per the hooks reference, a SessionStart hook that fires on resume receives context_tokens, estimated_cache_write_usd and prompt_cache_likely_expired. You can log these, or warn yourself before an expensive cold-cache resume.
  3. Cutting tokens with PreToolUse: the costs page includes an official PreToolUse hook on Bash. It rewrites npm test, pytest or go test so that only failure lines reach Claude. Anthropic's example says this kind of filtering can shrink context "from tens of thousands of tokens to hundreds" (Manage costs). To check it's active, run /hooks and look under PreToolUse.
  4. Live view: a custom status line receives session cost data and can show it all the time (Status line).

For a map of every hook event and when each one fires, see Claude Code Hooks Lifecycle: Every Event, Explained.

Limitation: --bare skips hooks. If your CI runs use bare mode, a PreToolUse filter in ~/.claude won't run. Pass the settings with --settings instead (headless docs).

Where to see real billing: Console and APIs

For money you are actually charged on an API key, the Claude Console is the source of truth.

How to reduce token usage

Most token waste comes from context you no longer need. Anthropic lists these levers (Manage costs):

For context: across enterprise deployments, Anthropic reports an average of about $13 per developer per active day, and under $30 for 90% of users (Manage costs). Your numbers will differ, so measure your own first.

Next steps

DIY today:

  1. Run /usage at the end of your next session and write down the total and the Prompt cache hit share.
  2. Put --output-format json --max-budget-usd on one recurring claude -p job and log total_cost_usd to a CSV.
  3. If you use an API key, set Spend limits on the Claude Code workspace in the Console.

If you'd rather not manage per-token billing yourself: a Claude subscription replaces per-token bills with plan limits. Pro is $20/month billed monthly, and Max starts at $100/month. Both include Claude Code (as of October 2026; check the official pricing page).

Related guides on this site:

FAQ

Does Claude Code still have a /cost command?

Current documentation puts session token and cost figures under /usage, though the changelog still mentions /cost in recent entries. If /cost behaves differently from an old guide, run /usage. You'll find the same Session block there.

How do I see token usage for claude -p runs?

Add --output-format json and read total_cost_usd with jq. For live events, use --output-format stream-json --verbose; the last line is a result message that includes the cost (headless docs).

Why doesn't the /usage cost match my bill?

Claude Code calculates the figure locally at list price. Pricing changes and billing rules it can't model make the two drift apart. Use the Console Usage page or the Usage and Cost API for the real numbers.

Can a hook stop Claude Code when it gets too expensive?

Not directly, because Stop and SessionEnd hooks don't receive cost data. Use --max-budget-usd for a hard cap on headless runs, and a Console spend limit for a cap Anthropic enforces.

Do Pro and Max users need to watch token costs?

Not in dollars, since usage is included in the plan. Do watch the plan bars and the 24h/7d breakdown in /usage, because long contexts and cache misses use up your limits faster.

Sources

Spotted something out of date or wrong? Tell us at shigoto.ai.note@gmail.com. We check every guide against its official sources.

Keep reading