DEV Community

Cover image for Claude Code: How to See Token Usage (and Reduce It)
Aoba Works
Aoba Works

Posted on Originally published at en.aobaworks.com

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

#claudecode #tokenusage #costtracking #headless

Originally published at Unattended.

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 situation What to pick first First page to open
Beginner, interactive sessions only /usage inside Claude Code Manage costs
Daily work on a Pro/Max subscription /usage plan bars plus the 24h/7d breakdown Manage costs → Plan usage breakdown
Recurring headless jobs (cron, CI) --output-format json + --max-budget-usd Run Claude Code programmatically
Tight budget on an API key Workspace Spend limits in the Console Workspaces
Want numbers for a dashboard Usage and Cost Admin API or OpenTelemetry Usage and Cost API
  • Beginner: /usage needs no setup. It is the quickest way to learn what a normal session costs you.
  • Daily work: on a subscription, the dollar figure doesn't affect your bill. The plan bars and the attribution breakdown are what show how fast you're using your limits.
  • Budget: a spend limit in the Console is enforced by Anthropic. Local estimates can't cap anything.

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

  • The dollar figure is calculated locally at list price. It is an estimate, not an invoice (Manage costs).
  • On a subscription, the Session cost line doesn't matter for billing. The plan bars do.
  • /usage reads local session history only. Usage from other machines or claude.ai is not included.
  • The token count next to the spinner (for example ↓ 5.5k tokens) counts only the output of the current turn. It will never match the session totals.

Common mistakes and fixes

  • "My total went back to $0." /clear starts a new session and resets the Session block (v2.1.211 and later). Note the number before you clear.
  • "/usage shows old bars." If the usage endpoint is rate-limited, you'll see Showing last-known usage. Press r to retry.
  • "The cost doesn't match my bill." That's expected. Use the Console Usage page for the real figure.

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: 
   claude -p "Summarize open TODOs in src/" --output-format json | jq '.total_cost_usd'
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

  • Summing totals across --resume runs. A resumed run reports the whole conversation's total, including earlier runs (headless docs). Take the latest value. Don't add them up.
  • Trusting usage for subagent-heavy jobs. The usage field leaves out subagent tokens. total_cost_usd and modelUsage include them (Track cost and usage).
  • Billing customers from these fields. Anthropic says not to. They are client-side estimates.

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.

  • Usage page: go to platform.claude.com/usage for usage over time. When you first sign in to Claude Code with a Console account, a Claude Code workspace is created automatically to keep that traffic separate (Workspaces).
  • Spend limits: open Settings → Workspaces, select the workspace, then click Spend limits. This caps monthly spend and can alert you at thresholds you choose. You can't set limits on the Default Workspace (Workspaces).
  • Rate limits: on the Rate limits page, choose the workspace from the Workspace dropdown and click Edit next to a model (Workspaces).
  • Usage and Cost Admin API: /v1/organizations/usage_report/messages (buckets of 1m, 1h or 1d) and /v1/organizations/cost_report (daily). Both need an Admin API key, and the Admin API is not available to individual accounts. Data usually appears within 5 minutes (Usage and Cost API).
  • OpenTelemetry: set CLAUDE_CODE_ENABLE_TELEMETRY=1 to export claude_code.cost.usage and claude_code.token.usage to your own backend (Monitoring). This is worth it if you already run Grafana or similar. It's overkill for one laptop.

How to reduce token usage

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

  • Run /clear between unrelated tasks. It costs nothing. /compact has to read the whole conversation to summarize it, so it is itself a large request.
  • Use Sonnet by default. Save Opus for hard reasoning. Set model: haiku for simple subagents. Leaving Opus as the default is one of the two most common causes of surprise spend Anthropic names; long sessions that never get cleared are the other.
  • Keep CLAUDE.md under about 200 lines. Move workflow-specific instructions into skills, which load only when needed.
  • Prefer CLI tools such as gh over MCP servers where possible. Turn off unused servers in /mcp, and run /context to see what's taking up space.
  • Lower the effort level with /effort on simple jobs. Thinking tokens are billed as output.
  • Be careful with agent teams. In plan mode they use about 7x the tokens of a standard session.
  • Watch idle costs. Scheduled /loop tasks resend your full context on every run. Background work, such as summarizing past conversations for --resume, typically costs under $0.04 per session.

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).

  • Suits: people who mainly work interactively and want a predictable monthly cost.
  • Not for: CI or --bare jobs that need an API key, or anyone who needs exact per-run invoices.
  • Limitations: plan usage resets on a rolling five-hour window and a weekly window, and going past the limit requires usage credits (Claude pricing).

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

This article was created with the help of AI. Sources are linked inline; check the official documentation for the latest details.

Top comments (0)