The short answer
- Where it lives:
~/.claude/projects/— one JSONL transcript per session, on your Mac, uploaded nowhere. - The four token types: input, output, cache-creation, and cache-read — each priced differently. Reading usage is mostly about seeing that split.
- The numbers that matter: cost, total tokens, cache hit rate, sessions, and burn rate (a rolling daily average).
- Fastest ways to see them:
/costin-session,npx ccusagein the terminal, or a visual dashboard like Dinoradar for history and trends.
Where Claude Code keeps your usage
Every time you run Claude Code, it appends to a plain-text
.jsonl transcript under ~/.claude/projects/,
with one folder per project directory. Each line is one turn, and it
records the model used and four token counts: input, output,
cache-creation, and cache-read.
That local file is the single source of truth. The built-in
/cost command, the ccusage CLI, and
Dinoradar all read the same JSONL — none of them phone home. So
"reading your usage" really means parsing those numbers and making
sense of them.
The four token types (and why they're priced apart)
Almost every confusing usage number comes down to not knowing which of these four buckets a token landed in:
| Token type | What it is | Relative price |
|---|---|---|
| Input | New text you send this turn | 1× |
| Cache write | Context stored for reuse (first time) | ~1.25× |
| Cache read | Context re-served from cache | ~0.1× |
| Output | What Claude writes back | ~4–5× |
The takeaway: raw token count tells you almost nothing on its own. A million cache-read tokens costs a tenth of a million input tokens and a fiftieth of a million output tokens. A good usage view always splits tokens by type — a single "1.4B tokens" number is noise until you know the mix.
The five numbers worth reading
1. Cost
The bottom line, in dollars. On API billing this is computed from the per-token rates for each model; on a subscription it's an equivalent cost (what those tokens would have cost at API rates) — useful for comparing sessions even when your monthly bill is flat. Always read cost per period and per project, not just as one lifetime total.
2. Cache hit rate
The share of your prompt-side tokens served from cache instead of at
full price: cache_read ÷ (input + cache_creation + cache_read).
On long sessions that re-send the same context every turn, a healthy
rate is often 60–90%. A low rate usually
means short, scattered sessions, or context that keeps changing so
there's little for the cache to reuse.
3. Total tokens (split in / out)
Read it as two numbers, not one. Input-heavy sessions mean lots of re-sent context (a candidate for caching or a leaner working set). Output-heavy sessions mean Claude is generating a lot — big files, verbose explanations — which is the pricier direction per token.
4. Sessions
How many distinct Claude Code runs happened in the period. Divide cost by sessions and you get a rough "what does one task cost me" gut-check that's more stable than any single day.
5. Burn rate
A rolling average of daily spend — Dinoradar uses a 7-day average. It answers "how fast am I burning right now," independent of which period you're viewing, and it's the number to watch if you're trying to stay under a monthly target.
Three ways to actually see them
- Built in —
/cost: run it inside a session for a rough running total. API billing only, current session only, no history. - ccusage:
npx ccusageprints daily and per-session token tables in your terminal. Great for a quick text dump; we compare it in Dinoradar vs ccusage. - Dinoradar: a native macOS dashboard that charts spend, the token split, cache savings, per-project cost and burn rate over time — computed locally, nothing leaves your Mac.
How to read a usage dashboard in 30 seconds
- Start with burn rate. Is your current daily pace where you want it? That's the "am I okay" glance.
- Check cache hit rate. If it's low for long sessions, that's your biggest lever — see how to reduce Claude Code costs.
- Scan top projects by cost. One repo almost always dominates. That's where any optimization pays off most.
- Glance at the timeline. A sudden spike on one day is worth a look — it's often a runaway loop, not a productive day.
That last one matters more than it sounds: a single stuck agentic loop can quietly out-spend a whole normal week. We cover how to catch it in Claude Code runaway costs.
Frequently asked
Where does Claude Code store usage data?+
In JSONL transcripts under ~/.claude/projects/, one folder per project. Each line records the model and the input, output, cache-creation and cache-read token counts for a turn. Nothing is uploaded — this local history is what every usage tool reads.
How do I check my Claude Code token usage?+
Run /cost in a session for a rough running total (API billing), or npx ccusage for daily and per-session token tables. For a visual, historical view that splits tokens by type, a dashboard like Dinoradar reads the same local files and charts them over time.
What is a good cache hit rate for Claude Code?+
It's the share of prompt-side tokens served from cache instead of full price. On long sessions that re-send context every turn, 60–90% is healthy. A low rate usually means short, scattered sessions or frequently changing context, where the cache has little to reuse.
Why is my Claude Code token count so high?+
The API is stateless, so every turn re-sends the whole conversation as input tokens. A long session with big files loaded pays for that context on each message, so input tokens dwarf output. It's normal — and it's exactly why prompt caching, which discounts those re-sent tokens, matters so much.
See your usage, not just your bill.
Dinoradar reads your own history locally and charts tokens, cost, cache savings and burn rate over time. Free forever · Pro $29 once.