Track Claude Code Token Usage and Cost

To see Claude Code token usage, run /usage in the session: it 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 transcripts in ~/.claude/projects/, such as ccusage (terminal reports) or PromptConduit (per-prompt cost in your editor, tagged with repo and branch). For the bill 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).

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.
• 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 90-day history across machines, a weekly digest, or shared rollups for a team, see pricing. Pro is $10 per month; Team is $15 per seat per month.