Claude Code Token Usage: How to Check and Track It

Run /usage (alias /cost) for the session and plan view, add a status line for always-on numbers, and use OpenTelemetry when you need numbers for a whole team. Those three cover almost every way to see Claude Code token usage. This page is about measuring. When you know where the tokens go, our guide to reducing Claude token usage covers how to cut them.

Every command, field and figure here was checked on 25 Oct 2026 against Anthropic’s costs, commands, status line and monitoring docs.

Which tool answers which question

You want to know	Use	Works on
Tokens and estimated cost for this session	/usage, Session block	Every plan and the API
How much of my 5-hour and weekly limit is gone	/usage plan bars, or a status line	Pro, Max, Team, Enterprise
What used my allowance (skills, subagents, MCP servers)	/usage breakdown	Pro, Max, Team, Enterprise
What fills the context window right now	/context	Everyone
Cost of one scripted run	claude -p --output-format json	Everyone
Usage per developer across a team	OpenTelemetry, Console or org analytics	Teams and API orgs

How Claude Code token usage works

Claude Code is billed, or counted against your plan, by API tokens. Four kinds show up in the numbers:

• Input tokens: your prompt plus everything Claude Code sends with it: the conversation so far, CLAUDE.md, tool definitions and tool results.
• Output tokens: what Claude writes back, including tool calls and thinking.
• Cache writes: input stored in the prompt cache so later requests can reuse it.
• Cache reads: input served from that cache, at a much lower rate than fresh input.

The key fact from Anthropic’s costs guide: Claude Code sends your full conversation with every request, and each batch of tool results triggers another request. That is why a one-line question late in a long session still costs a lot, and why cache reads are often the biggest number in a long session. The guide also lists background usage, such as summarising past conversations for claude --resume, typically under $0.04 per session.

1. Check the session with /usage

Type /usage at the Claude Code prompt. /cost and /stats open the same screen. The Session block looks like this:

Total cost:            $0.55
Total duration (API):  6m 20s
Total duration (wall): 6h 33m 10s
Total code changes:    0 lines added, 0 lines removed
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

How to read it:

• The dollar figure is an estimate. Claude Code computes it locally at list price. On Pro and Max, usage is included in your plan, so the session cost is not what you pay. API users should confirm real spend on the Console’s Usage page.
• It resets on /clear. Since v2.1.211 the totals start again at $0 when /clear starts a new session.
• A Prompt cache (main) line (v2.1.251 or later) shows the share of input served from cache and how many requests missed it. A low cache share means you are paying full price for re-sent context.

On Pro, Max, Team and Enterprise plans, the same screen shows your plan usage bars and a breakdown of recent usage by skill, subagent, plugin and MCP server, with recommendations such as 25% Trim ~/code/api/CLAUDE.md · 49k tokens per request. Press d or w to switch between the last 24 hours and 7 days. These figures come from session history on this machine, so usage on other devices or claude.ai is not included.

Two more readouts help while you work:

• /context draws the current context window as a grid and names the heaviest items. It answers “why is every request so big?”
• The spinner count, as in (10m 27s · ↓ 5.5k tokens), is the output the current turn has produced so far. It ignores input, so it will not match /usage.

For a longer view of how you work, /insights writes an HTML report on your recent sessions to ~/.claude/usage-data/report.html. It uses tokens itself.

2. Keep the numbers on screen with a status line

A status line is a script Claude Code runs to draw the bar under the prompt. It receives JSON on stdin, including:

Field	What it holds
context_window.used_percentage	How full the context window is, from input tokens only
context_window.total_input_tokens	Tokens in the context window after the latest response
cost.total_cost_usd	Estimated session cost at list price
rate_limits.five_hour.used_percentage	Share of the 5-hour limit used (Pro and Max)
rate_limits.seven_day.used_percentage	Share of the weekly limit used (Pro and Max)

A minimal setting in ~/.claude/settings.json shows the model and context use:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

The rate_limits fields appear only for claude.ai Pro and Max subscribers and only after the first response, so read them with a // empty fallback. Our status line guide explains every field. If you’d rather not write the script, the Usage Meter kit puts model, context and both plan limits in the status line with one setup command.

3. Track scripted runs

Headless runs report their own usage. With --output-format json, the response includes total_cost_usd and a per-model breakdown:

claude -p "Summarize this project" --output-format json | jq '.total_cost_usd'

Add --max-budget-usd 5.00 to stop a print-mode run once its estimated spend reaches the cap. Spend from subagents counts toward it. In the Agent SDK, the final ResultMessage carries the same total_cost_usd, and model_usage breaks it down per model, subagents included. The SDK cost tracking docs explain how to avoid double-counting across steps.

4. Track a team with OpenTelemetry

For per-developer numbers in your own dashboards, turn on Claude Code’s OpenTelemetry export:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
claude

The two metrics that matter for usage are claude_code.token.usage (tokens, broken down by type: input, output, cacheRead, cacheCreation) and claude_code.cost.usage (estimated USD). Both carry a model attribute and the user’s account, and you can split them by team once you set a custom attribute such as team.id in OTEL_RESOURCE_ATTRIBUTES. Admins can push the same variables to every developer through managed settings; a repository’s own .claude/settings.json cannot turn telemetry on.

Built-in dashboards, depending on how your team signs in:

• Team and Enterprise plans: the spend report in org analytics, with CSV export. Usage inside each seat’s allowance is not metered in dollars.
• Claude Console (API): the Usage page, the Claude Code dashboard and the Claude Code Analytics API, per user.
• Bedrock, Google Cloud, Foundry: your cloud billing console, plus OpenTelemetry.

What “normal” looks like

Anthropic’s costs guide gives one benchmark: across enterprise deployments, the average is around $13 per developer per active day and $150 to $250 per developer per month, with costs below $30 per active day for 90% of users. Use it to sanity-check a pilot, not as a budget.

Claude Code token usage vs chat

On a paid plan, chat on claude.ai and Claude Code draw on the same usage limits. Claude Code spends them much faster: each turn carries file contents, tool calls and multi-step reasoning, and Anthropic’s costs guide says one debugging session can consume more than a day of chat. How those limits work is covered in Claude usage limits explained.

When the numbers look wrong

Usage that climbs while you are idle usually has one of these causes, all listed in the costs guide:

• A long context re-read on every request.
• Cache misses after a break longer than the cache lifetime.
• Scheduled tasks such as /loop, which send your full context on each run.
• Subagents, workflows and agent teammates, each sending its own requests.
• /compact on a large conversation, which is itself a large request. /clear costs nothing.

Once you can see which of these applies, the fixes are in how to reduce Claude token usage. If your startup files are the problem, the Token Diet kit lists everything Claude Code loads at the start of each session.