Quick answer
Claude Code writes a JSONL log per session under `~/.claude/projects`, containing message records with input, output, cache read, and cache write tokens. A usage report groups those records by session, model, and day. UsageAtlas builds the report locally and shows 7, 30, or 90-day ranges.
The fields that matter
| Field | Meaning | Why |
|---|---|---|
| input_tokens | Fresh context | Main cost driver |
| cache_read_input_tokens | Cached context reused | Discount |
| cache_creation_input_tokens | Context written to cache | First-turn cost |
| output_tokens | Generated tokens | Answer size |
| model | Model ID | Per-model split |
| sessionId | Session grouping | Per-task cost |
Build the report
- Locate the project folder under
~/.claude/projects. - Parse each JSONL line and keep assistant message records.
- Sum the four token fields per session.
- Group by day and model.
- Apply current rates only if you need a cost figure.
ls ~/.claude/projects
# each directory maps to a project path
head -n 1 ~/.claude/projects/<project>/<session>.jsonlCaveats
- Logs are per machine; other devices are not included.
- Deleted sessions disappear from the report.
- Cost is an estimate unless the log records it.
- Cache fields are absent in older logs.
UsageAtlas handles the parsing and keeps the raw files untouched.
Produce a token report
- Collect the local session files for the period.
- Sum input, cached input, output, and cache-write tokens separately.
- Group by day and by model.
- Apply current rates to get an estimated cost.
- State the period and the source in the report header.
total = input + cache_read + cache_write + output\ncost = sum(tokens * rate_for_type)Keep cached tokens separate or the report will overstate cost badly. The cache read guide explains the rate, and UsageAtlas produces the same breakdown from the same files.
Questions, answered
Where does Claude Code store token data?
In JSONL session logs under ~/.claude/projects, with an alternate location under ~/.config/claude/projects on some installs.
Does Claude Code report cost?
It can show a session cost estimate with the cost command. Historic logs contain tokens, so cost is usually recomputed.
Can I export the report?
Yes, as CSV from a script or a tracker. The export guide covers the column set.