How to see your token usage in Claude Code

Where your own numbers appear

There are four places, and they answer different questions. Two are commands you run, one is a counter that runs while Claude is working, and the fourth is a script you write once and then read without doing anything.

1. /usage, which also answers to /cost

Anthropic's command reference describes /usage as session cost, plan usage limits and activity stats in one screen, and lists /cost and /stats as aliases of it, so they run the same command. The top of that screen is the Session block, and it is where your token counts are:

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)

Read the four figures under each model left to right as input, output, cache read and cache write. In a session that has been open for a while the largest of them is almost always cache read, which is not a warning: Claude Code sends the whole conversation with every request, so the unchanged part keeps arriving as cached tokens rather than fresh input.

That dollar figure is one sentence here and no more: Claude Code computes it locally from the token counts at list price, and Anthropic calls it an estimate, with the Usage page in the Claude Console as the authoritative bill.

On a subscription, Anthropic says the Session block is intended for API users: Claude Max and Pro subscribers have usage included, so the session cost figure is not what bills them. What they get on the same screen is plan usage bars, activity stats and a usage breakdown. And the totals are per session in the strict sense — /clear takes them back to zero. Before v2.1.211 they kept adding up for the life of the Claude Code process, which is worth knowing if you are reading an old build.

What the plan breakdown adds on a subscription

On a Pro, Max, Team or Enterprise plan there is more on that screen: a breakdown of what counts against your plan limits. The first part is attribution: recent usage split between skills, subagents, plugins and individual MCP servers, each as a percentage of your total, where a server's share counts only the requests that actually consumed one of its tool results — a v2.1.222 fix, before which one call made every later request count against that server.

The next part is recommendations, one suggested change per row, and each row opens with the share of your recent usage it applies to, as in 25% Trim ~/code/api/CLAUDE.md · 49k tokens per request. Read that number carefully: it says how much of your usage the row covers, not how much the change would save, and one request can count toward several rows, so the shares can add up past 100%. Press d or w to switch between the last 24 hours and the last 7 days, and f to have Claude Code act on the recommendations it can (v2.1.305 or later). Two things to know about those figures: they are approximate, and they come from local session history on this machine, so work on your other devices or in claude.ai is not counted.

There is also a Loops part (v2.1.242 or later), which lists the heaviest session-scoped scheduled tasks that ran recently, ordered by total tokens, with how often each fires, how many times it ran, its total and per-run tokens, and when it last ran. If a loop you left running is spending, this is where it shows up.

The prompt cache line, and why it is the one to read

From Claude Code v2.1.251, a session also gets a Prompt cache (main) line once the main conversation has had its first API response. It is a summary of cache behaviour rather than a running total:

Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)

The percentage tells you how much of what you sent was served from cache instead of processed fresh. The misses tell you the opposite: each one is a request that re-processed content the cache already held, with how long ago it happened and how many tokens were written back. Anthropic also separates a mistake from an expected rebuild, and that distinction is the useful part: when Claude Code has just compacted the conversation or cleared old tool results, it counts that miss as an expected rebuild rather than as something you did wrong. Where it can identify a likely cause for a real miss it names one, such as likely cause: tool definitions changed (v2.1.260 or later).

The line ends by telling you whether the cache is still warm, with the lifetime in effect. A cold cache is the expensive state, so a line that reads cold with a long idle time next to it explains a bigger request than you expected. Two limits on it: it covers the main conversation only and not subagents, and /clear resets it along with the rest of the Session block.

2. The count beside the spinner

While Claude is working, the line beside the spinner can end with a time and a token count, as in Deciphering… (10m 27s · ↓ 5.5k tokens). It is the output this turn has produced so far, and it is deliberately narrow: it leaves out everything Claude Code sends to the model, so your prompt and the whole conversation do not move it, and it resets at the start of every turn and at every compaction. It also does not appear in screen-reader mode. Treat it as a sign of how much writing a turn is doing, never as a session total.

3. /context for the window, not the total

The other command worth knowing is /context. Anthropic describes it as a coloured grid of current context usage with optimization suggestions for context-heavy tools, memory bloat and capacity warnings, and passing all expands the per-item breakdown. The difference from /usage is what question it answers: /usage is a running total of what the session has spent, and /context is a snapshot of what is in the window right now. When a session feels expensive, this is the command that shows you which part is big.

4. A status line you write yourself

If you would rather not run a command, Claude Code can keep a number on screen. A custom status line is a shell script you configure, and Claude Code pipes JSON session data into it on stdin and prints whatever you return. The fields for this job are in two objects: context_window carries total_input_tokens and total_output_tokens from the most recent API response (input includes cache reads and writes), plus context_window_size, and pre-calculated used_percentage and remaining_percentage; cost carries total_cost_usd, the estimated cost of every API call in the session, which also resets to zero on /clear.

Two cautions before you build one. The context_window numbers are about the window, not about spend: they describe what is in front of the model, so they do not add up into a session bill. And several of these fields can legitimately be absent or null — used_percentage can be null early in a session, and current_usage is null before the first API call and again after /compact until the next response — so a script that dereferences them without a fallback prints garbage in the first minutes of a session.

One more view that is about something else: /insights writes an HTML report on how you work rather than how many tokens you used. It analyses up to 200 of your recent local sessions and lands at ~/.claude/usage-data/report.html, with a timestamped copy of each run, and Claude Code deletes those reports on the same 30-day schedule as the rest of your session data. It is worth running once; it is not a usage meter.

Where a team reads them, and which dashboard is the wrong first stop

This is the part that trips people up, because the obvious place is the wrong one. Anthropic's own documentation for the analytics dashboard lists what it reports — lines of code accepted, suggestion accept rate, daily active users and sessions, plus contribution metrics and a leaderboard with CSV export — and then says where per-user token counts come from instead: OpenTelemetry export, or the spend report from your organization's analytics settings, which lists token usage and estimated usage-credit spend per user and per model. So the dashboard is an adoption view, and the token numbers live one step away.

API customers get a different dashboard at platform.claude.com/claude-code, which is closer to what people expect: lines of code accepted, accept rate, an activity chart, daily API spend in dollars, and a team insights table with each member's spend and accepted lines for the month. The caveat is on the same page — those spend figures are estimates for analytics purposes, and the billing page is the actual cost.

For real per-user token numbers there is one answer that works on every setup, including Amazon Bedrock, Google Cloud and Microsoft Foundry: OpenTelemetry. Set CLAUDE_CODE_ENABLE_TELEMETRY=1 and choose an exporter with OTEL_METRICS_EXPORTER (otlp, prometheus, console or none), and Claude Code emits:

The accounting rule matches what /usage shows, and it is the one people get wrong: the input type excludes tokens read from or written to the prompt cache, which arrive under cacheRead and cacheCreation, and cacheCreation adds five-minute and one-hour cache writes together. A dashboard that sums only input therefore misses the cached tokens entirely, and in the example above they are the largest of the four figures.

Two traps, both documented. Claude Code ignores the OpenTelemetry exporter variables in a repository's .claude/settings.json and .claude/settings.local.json, so a checked-in config that appears to set them does nothing. Anthropic's route is managed settings, or each developer setting them in their shell or ~/.claude/settings.json. And Claude Code does not pass OTEL_* variables to the subprocesses it spawns, including the Bash tool, hooks, MCP servers and language servers, so a hook that tries to report its own telemetry will not see them. If nothing arrives, Anthropic's own check is to look for claude_code.session.count at your backend and to run claude --debug-file <path>, where exporter failures appear as [3P telemetry] errors. With prometheus as the exporter, metrics are scraped from http://localhost:9464/metrics.

What actually reduces them

One idea explains nearly all of it: token cost scales with context size. Claude Code sends your conversation with every request, and every time it uses a tool it sends another request carrying those results. Anthropic already softens that with prompt caching and auto-compaction; everything below is about keeping the thing being cached and compacted small in the first place. Asked, for an unexpectedly high bill on an API or cloud-provider plan, which habits matter most, Anthropic names two: clearing between unrelated tasks, and matching the model to the job.

Three catches worth knowing

Thinking is billed as output tokens, and the default budget can be tens of thousands of tokens per request depending on the model, so lowering the effort level moves the number. It also cannot always be turned off: Anthropic says thinking cannot be disabled on Opus 5.5, Sonnet 5.5, Haiku 5.5 or the Fable models, which always use it, and adaptive-reasoning models ignore a fixed MAX_THINKING_TOKENS budget, so effort level is the lever there instead.

Subagents keep verbose output out of your conversation, but they are not free: Anthropic says plainly that a subagent's own requests still draw on your usage, so delegating adds a second stream of requests rather than moving the work off the meter. Choose a smaller model for a subagent, or put every subagent on one model, when the point is saving.

Agent teams are a different class of cost: Anthropic measures them at approximately 7x the tokens of a standard session when teammates run in plan mode, because each teammate keeps its own context window. If you are watching tokens, that is the feature to switch on deliberately and turn off when the work is done, rather than leave running.

Why a long session costs more than it looks

If a session's numbers surprise you, this is Anthropic's own list of reasons it happens, and most of them are invisible while you work:

• Long context. Your full conversation goes with every request, and each tool call sends another one carrying that batch of results, so a one-line question in a session open all day still draws usage for the whole conversation.
• Cache misses. The first message after a break longer than the cache lifetime reprocesses your whole context instead of re-reading it cheaply.
• Scheduled tasks. A session-scoped scheduled task fires on its interval even while the session is idle, sending the full context each time.
• Cross-session messages and goal check-ins. Both start a new turn while the session sits idle, and a turn means your full context.
• Subagents, workflows and agent teammates. Every one of them sends its own requests on top of the main conversation's.
• Compaction itself. /compact reads the conversation it summarises, so compacting a large context is a large request in its own right — which is the argument for /clear when you want a fresh start rather than continuity.

The tool also spends a little on its own account: background work such as summarising conversations for --resume, and the request behind a command like /usage. Anthropic describes that as a small amount of tokens, so it is rarely where a large bill comes from — the reasons above are.

What this page leaves to other pages

Three subjects sit right next to this one, and this page answers none of them. Keeping them apart is deliberate, because a page that tried to answer all of them would answer none of them well.

One warning belongs here rather than on either of those pages, because it looks like a token problem and is not: a context warning or an auto-compact warning is not a usage limit. It means the conversation has grown close to the point where Claude Code summarises older history, and the advice it points at is reducing token usage.

Where Omniscio fits

Everything above is Claude Code's own surface, and you need none of it from us. Omniscio, the desktop app we make for running many Claude Code sessions at once, adds a per-session readout because with a dozen sessions open the question stops being “what did this session use” and becomes “which one is expensive”. Every session carries a cost chip in its header, which explains itself on hover as the estimated session cost, and a Session Stats block in the session's ⋯ menu with the same session's cost, turn count and token totals. The chip appears for every session, metered or subscription-billed, and only a provider that can report tokens but not a real dollar cost gets it marked as an estimate. Token totals there are abbreviated, so a large count reads rounded rather than to the last digit.

The aggregate view is Stats, a built-in virtual project in the Omniscio group of the sidebar. Its Overview tab adds up value, input and output tokens, LLM time and active time across every session, with a per-project table and a Top Sessions list; Trends charts tokens per day; Spend splits the total between coding sessions and the background features that also spend; and a Time Range selector covers today, yesterday, 7, 30 or 90 days, or all time. One honest limit on the token charts: the per-day ledger began on 4 October 2026 and there is no backfill, so a session that ran before then has all of its tokens counted on its start day.

Two neighbouring views are worth naming so you go to the right one. Context Details, in the same ⋯ menu, is the app's version of /context: a popover that breaks the current window down by source, so you can see whether the system prompt, skills, memory or an MCP server is taking the room. And the Usage tab under Stats is the app's four-chart rate-limit forecast, while the per-account bars with their plain-English ETAs live in the Accounts popover. That one is about the limit rather than the spend, and it is the only view on this page that asks whether you are blocked rather than what you used.

One boundary to state plainly, because it is easy to assume otherwise: Omniscio's per-session spend cap only limits sessions billed to a pay-per-use API key. A session running on a Claude Pro or Max subscription is never spend-capped by the app, so a token total you see there is information, not a ceiling. The free plan is a real plan and not a trial — 8 projects and 10 agents running at once — and Pro is $20/month or $192/year.

The Stats page in the library covers every tab and figure in full, the session cost, tokens and turns page covers the per-session readouts, and Context Details covers the window breakdown. The features page lists what else is in the app and the download page has the installers.

How this page was checked

Checked against Claude Code 2.1.310 documentation, October 25, 2026. Every statement here about Claude Code comes from Anthropic's own documentation, read in its Markdown form on that day, from the pages listed below; where a behaviour has a minimum version, the version is in the text rather than left implied. No session was profiled to write this page, so the numbers it shows are the examples Anthropic's documentation prints, not a capture from anyone's machine.

What this page says about Omniscio comes from our own product pages, the library and our source code, and the library link for each claim is in the ledger beside this page. If Anthropic's documentation and this page ever disagree about Claude Code, Anthropic's is right — this surface changes on nearly every release.

Sources

Anthropic's Claude Code documentation, read October 25, 2026, at Claude Code 2.1.310:

• Manage costs effectively: the /usage Session block and its example output, the Prompt cache (main) line, the plan usage breakdown with its attribution, recommendations and Loops parts, the d/w toggle and the f shortcut, the spinner count, /insights, background token usage, and the whole “reduce token usage” and “why usage climbs” sections
• Commands reference: /usage with its /cost and /stats aliases, and /context, /compact, /clear, /model, /effort and /insights
• Customize your status line: the context_window fields, their units, the cost fields, and which of them can be null and when
• Monitoring with OpenTelemetry: the metrics and events, the token-type accounting rule, the exporter variables, the Prometheus endpoint, the debug check, and the two traps (settings files ignored, OTEL_* not passed to subprocesses)
• Track team usage with analytics: what each dashboard shows, that per-user token counts come from OpenTelemetry or the spend report, and that Console spend figures are estimates
• The changelog: release 2.1.310 of October 23, 2026, the newest listed when this page was checked

Omniscio's own pages and library, for the Omniscio section:

• Session cost, tokens and turns: the header cost chip, the Session Stats block, and the fact that token totals are abbreviated
• Stats: the tabs, the Time Range selector, and the 4 October 2026 start of the per-day token ledger
• Context Details: the per-source breakdown of what is filling the window
• Usage Forecast: the per-account bars and plain-English ETAs in the Accounts popover
• Pricing: the free plan and the Pro price
• Features: what else is in the app today

Common questions

How do I see token usage in Claude Code?

Run /usage in a session (the /cost and /stats aliases run the same command). Its Session block lists the cost, the durations and the code changes, then a Usage by model line with input, output, cache read and cache write tokens for each model you have used.

Does the /usage total reset?

Yes, when /clear starts a new session the totals go back to zero. Before v2.1.211 they kept adding up for the lifetime of the Claude Code process instead.

Why is my cache read number so much bigger than input and output?

Because Claude Code sends the whole conversation with every request and prompt caching lets the unchanged part be re-read at the cached rate. Anthropic counts those re-reads as cache read tokens, separate from input, so in a long session cache read is usually the largest of the four figures rather than a sign something is wrong.

Does Claude Code's analytics dashboard show token counts?

Anthropic's analytics dashboard reports lines of code accepted, suggestion accept rate, daily active users, sessions and contribution metrics. For per-user token counts and cost estimates, Anthropic points at OpenTelemetry export, or the spend report from your organization's analytics settings.

What is the difference between /usage and /context?

/usage reports what the session has spent: cost, tokens per model and activity. /context shows what is in the context window right now as a coloured grid, with suggestions for what is taking the most room. One is a running total, the other is a snapshot of the window.

What reduces token usage the most?

Keeping the context small. /clear between unrelated tasks, /compact with focus instructions when you need continuity, a smaller default model for ordinary work, and disabling MCP servers you are not using all shrink what every request has to carry. Asked about unexpectedly high spend on an API or cloud-provider plan, Anthropic names two highest-impact habits: clearing between unrelated tasks and matching the model to the job.

Can I watch token usage continuously instead of running a command?

Yes. A custom status line is a script Claude Code runs with session data on stdin, and it can print context window percentage, context token totals, estimated cost and elapsed time in the bar at the bottom of the screen.