How to Check Claude Code Token Usage and Cost

Quick answer

Goal	What to run or open
Check token usage and cost for this session	/usage in Claude Code (/cost and /stats are the same command)
See plan limits (Pro, Max, Team, Enterprise)	/usage — usage bars, d/w for 24h vs 7d breakdown
Keep usage visible while you work	Configure a status line (/statusline or statusLine in settings)
See why tokens exist before your first prompt	/context — system prompt, CLAUDE.md, skills, MCP listings
History across sessions on this machine	ccusage, or PromptConduit reading ~/.claude/projects/ (transcript layout)
Authoritative billing (API / Console)	Claude Console Usage page

To see Claude Code token usage in the active session, run /usage: the Session block lists input, output, cache read, and cache write tokens per model with an estimated dollar total. For history across sessions, use a tool that reads the local JSONL transcripts in ~/.claude/projects/, such as ccusage (terminal reports) or PromptConduit (per-prompt cost in your editor, tagged with repo and branch). For the invoice itself, the Claude Console Usage page is the source of truth.

The rest of this guide compares those options, walks through a local setup, and explains how to read the numbers, especially the cache columns, which usually account for most of the tokens in a long session.

The options compared

Tool	Where the data comes from	Granularity	Cost shown?	Repo / branch attribution	Local only?
/usage in Claude Code (/cost and /stats are aliases)	The running session’s API responses	Current session, per model	Yes, estimated at list price (or your org’s configured rates)	No	Yes
ccusage	Local Claude Code JSONL files	Daily, weekly, monthly, per session, 5-hour blocks	Yes, USD	Per project with --instances	Yes
Claude Console	Anthropic billing	Organization and workspace; daily per-user metrics via the Claude Code dashboard and Analytics API	Yes, billed usage	No (per user, not per repo)	No, hosted by Anthropic
PromptConduit CLI + editor extension	Local transcripts and hook events	Per request, per prompt, per session, per model	Yes, API-equivalent USD	Yes: repo, branch, commit, open PR	Yes on the Free tier; cloud history is opt-in

Notes on each:

• /usage. Anthropic’s cost docs say the Session block shows API token usage for the current session and is “intended for API users”; on Pro and Max the session cost figure “isn’t relevant for billing purposes.” Totals reset when /clear starts a new session. Recent versions also add a Prompt cache (main) line with the share of input tokens served from cache.
• ccusage. A CLI you run with bunx ccusage, pnpm dlx ccusage, or npx ccusage@latest. It reports daily, weekly, monthly, session, and blocks, tracks cache creation and cache read tokens separately, and also reads other agents’ local data (Codex, Gemini CLI, and more). It is a strong choice if you want reports in the shell.
• Claude Console. If you authenticate Claude Code with a Console account, a “Claude Code” workspace is created automatically, and you can set workspace spend limits. This is where you reconcile invoices. It is not designed to tell you which git repo or prompt produced a spike.
• PromptConduit. Prices every API request locally against a bundled rate card and shows it in the editor status bar, so you see the cost before you send the next prompt. It also works for Cursor and several other agents (see supported tools).

Check plan limits, not just dollars

If you sign in with a Pro, Max, Team, or Enterprise plan, the number you usually care about is how much of your limit is left, not a dollar total. /usage shows that on the same screen as the Session block: plan usage bars, activity stats, and a breakdown that attributes recent usage to skills, subagents, plugins, and individual MCP servers, with recommendations such as trimming a large CLAUDE.md. Per Anthropic’s cost docs, the figures are approximate and computed from session history on the current machine, so usage from other devices or claude.ai is not included.

On Team and Enterprise plans, usage draws from a per-seat allowance that resets on a rolling five-hour window and a weekly window, shared with Claude chat and Cowork. Messages such as “You’ve hit your session limit” or “You’ve hit your weekly limit” mean one of those seat windows is exhausted; Anthropic treats them as shared across models, so /model does not restore access until the window resets. A separate model-family cap (for example Opus-only) can sometimes be cleared by switching models, which is a different limit. To continue past the allowance where usage credits are enabled, run /usage-credits — Pro and Max subscribers land in Settings → Usage on claude.ai; Team admins manage credits in the org console.

Show usage continuously with a status line

/usage is a snapshot. To keep numbers on screen, add a status line. Claude Code runs the command you configure and pipes session JSON to it on stdin. This inline version prints the model and context percentage:

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

Put it in ~/.claude/settings.json, or run /statusline and describe what you want. Fields from the status line docs worth knowing:

Field	Meaning
cost.total_cost_usd	Estimated session cost, at list price unless an admin configured rates. Resets on /clear
context_window.used_percentage	Share of the context window used, from input tokens only (output tokens excluded)
context_window.current_usage	Token counts from the last API call: input, output, cache creation, cache read
rate_limits.five_hour.used_percentage, rate_limits.seven_day.used_percentage	Plan limit consumed, 0 to 100. Present only for Pro and Max subscribers, after the first API response

Handle absent fields with a fallback such as // empty in jq, since each can be missing early in a session.

While Claude works, the spinner line can also show a live output token count for the current turn (for example ↓ 5.5k tokens). That number grows as the model streams and resets each turn; it does not include your prompt or cached context. Session totals still come from /usage.

Why tokens are used before you type anything (base context)

Claude Code sends your whole conversation with every request, and each tool call triggers another request carrying its results. The base context loaded before your first message includes the system prompt, tool definitions, CLAUDE.md, and skill and MCP listings — not a fixed token count you can look up (Anthropic does not publish one number; it changes with version and model). Run /context to see what fills the window today. Anthropic’s cost guidance is to keep CLAUDE.md short (aim for under 200 lines), move workflow-specific instructions into skills, which load only when invoked, and disable MCP servers you are not using. /clear between unrelated tasks, because stale context is paid for on every later request.

A small amount of usage also happens in the background: Anthropic says conversation summarization for claude --resume and some commands use typically under $0.04 per session.

How to track Claude Code cost per prompt with PromptConduit

No account is needed for any of these steps.

1. Install the CLI and wire the Claude Code hooks.

curl -fsSL https://promptconduit.dev/install | bash
promptconduit install claude-code

This adds hooks to ~/.claude/settings.json. In Free mode every event is written to ~/.promptconduit/events.jsonl and nothing is sent anywhere. The quick start covers the same steps in more detail.

2. Use Claude Code as usual, then check the session cost from the same directory.

promptconduit cost              # current session, human-readable
promptconduit cost --json       # same summary as JSON
promptconduit cost --cwd ~/code/api   # scope to another workspace

Illustrative output (the format matches the CLI; the numbers are made up):

AI session cost — claude-code  (exact)
  Total: $0.5526 USD
    claude-sonnet-4-6      $0.5526     in 1200 · out 5300 · cache-read 940000 · cache-write 50000
  Tools: 31 call(s)  (Read ×14, Bash ×9, Edit ×8)
  Signals: cache-hit 95% · input-share 0% · tier standard
           cache-miss cost share 35%

(exact) means the token counts were read verbatim from the transcript’s usage block, not estimated. The tool line lists tool names and counts only; tool inputs are never read.

3. Install the editor extension for live cost. In Cursor, search the Extensions pane for “PromptConduit” (it installs from Open VSX). The status bar then shows ⚡ <request cost> · 🕘 <session cost>. Click it, or run PromptConduit: Show Cost Breakdown from the command palette, to open a per-prompt ledger with Session, This branch, and This PR scopes. PromptConduit: Show All Sessions Cost gives a multi-session overview. Details are in the extension docs.

4. Inspect the raw events if you want to build your own report.

promptconduit events -n 5      # last five captured events
promptconduit events --raw     # include the full JSON envelope
promptconduit events --path    # print the log file location

End-of-turn Stop events carry a cost enrichment with a list of priced requests (request_id, model, tokens, usd, signals) and a vcs enrichment with repo, branch, and commit. The Cursor post has a jq recipe that rolls this up by repo and model.

How to read the numbers

Anthropic’s API reports four token counts on every response, and Claude Code writes them into the transcript. PromptConduit keeps the same four columns.

• Input (input_tokens): fresh prompt content that was neither read from nor written to the cache. Billed at the model’s base input rate.
• Cache write (cache_creation_input_tokens): content written into the prompt cache. Per Anthropic’s prompt caching docs, 5-minute cache writes cost 1.25x the base input price and 1-hour writes cost 2x. When the transcript records the TTL split, PromptConduit prices each part at its own rate; otherwise it uses the 5-minute rate.
• Cache read (cache_read_input_tokens): content served from an existing cache entry. Billed at 0.1x the base input price for most models; Anthropic lists lower multipliers for some newer models, so check the docs for yours.
• Output (output_tokens): everything the model generates. Thinking tokens are billed as output.

Total input for a request is cache_read + cache_creation + input. In a long agent session the cache read column is usually the biggest by far, because Claude Code resends the conversation on every request and the cache serves most of it. That is expected and cheap per token. What deserves attention:

• Cache hit rate. PromptConduit computes cache_read / (cache_read + cache_write + input). A low value on a long session means context is being rebuilt instead of reused. The cache hit rate guide covers the usual causes.
• Cache-miss cost share. The share of dollars spent on fresh input plus cache writes. High share with a low hit rate points at context being resent uncached.
• Tier. A coarse bucket (premium, standard, economy) from the model name. Opus-class work on routine edits shows up here.
• Tool calls. Many small tool calls mean many requests, each carrying the full context. See batching tool calls.

The dollar figures are what the same tokens would cost at pay-as-you-go API rates. On a subscription that is an “API-equivalent” number, useful for comparing sessions and models, not what you are charged.

Common pitfalls

• Treating the session total as your bill. Both /usage and PromptConduit estimate from token counts. Contracted rates, data residency multipliers, and cloud provider pricing (Bedrock, Vertex, Foundry) are not applied by PromptConduit. Reconcile against the Console or your cloud billing.
• Missing subagent spend. Subagents send their own requests. Claude Code’s Prompt cache (main) line covers the main conversation only. If a session looks cheap but your plan usage climbed, check subagent activity; the subagent guide explains when delegation saves tokens and when it costs more.
• Comparing across /clear. /usage resets on /clear. Session-level numbers in any tool are only comparable if you know where the session boundaries are.
• Idle gaps. The first request after the cache lifetime expires re-caches the full context, which shows up as a burst of cache write tokens. Per Claude Code’s docs, that lifetime is five minutes by default on an API key or cloud provider and an hour on a subscription unless you are drawing on usage credits.
• Unpriced models. If a model is not in PromptConduit’s rate table, tokens are still exact but the cost shows as unpriced rather than $0. Run promptconduit cost refresh-card to fetch the latest card from /model-rates, or promptconduit cost refresh-pricing to fill gaps from LiteLLM’s public price table. Neither sends any of your data.
• Paying twice for a wrong approach. Stopping a turn halfway through edits discards work you have already paid for, and the redo is billed again. Planning first and front-loading context cut most of that waste.
• MCP and CLAUDE.md overhead. Large tool definitions and instruction files ride along on every request. Run /context in Claude Code to see what fills the window, and read right-sizing MCP servers.

Privacy

The cost feature reads transcripts and hook payloads on your machine and stores numbers and identifiers only: token counts, dollar amounts, model names, tool names, and the basename of the working directory. Prompt text, tool inputs, and file contents are not part of cost records. Events stay in ~/.promptconduit/events.jsonl (30-day retention by default; see promptconduit prune) unless you run promptconduit login or set an API key. The security page covers the details.

When cloud history helps

Local tracking answers “what did this session cost?” If you want shared rollups for a team, by member, model, repo, and pull request, see pricing. Teams of up to 3 are free; Team is $99 per month flat for up to 15 members.

Related reading

• Claude Code transcripts: location and format — where ~/.claude/projects/ JSONL files live and how usage blocks are stored
• Claude Code OpenTelemetry cost export — stream per-request cost_usd into your observability stack
• Attribute AI coding spend to teams and repos — chargeback patterns when several developers share a codebase
• Cursor AI spend by repo and model — same PromptConduit log when you use both agents