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

Posted on Oct 17 • Originally published at en.aobaworks.com

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.

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

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

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

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

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

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.

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

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

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.

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

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.

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

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.

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.

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.

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