How to check Claude Code token usage locally

You can check Claude Code token usage from the JSONL transcripts already on your computer. Run npx tokenforest forest to scan them and print totals by token class, model, project, and day. The scan happens locally. You do not need to create an account to see the result.

The short version

Open a terminal and run:

npx tokenforest forest

For a fixed time window, add --since and a number of days:

npx tokenforest forest --since 30

For machine-readable output:

npx tokenforest forest --json

The JSON result includes raw token classes, weighted tokens, tree progress, sessions, projects, models, sources, and daily totals.

Where Claude Code stores token usage

Claude Code writes project transcripts beneath ~/.claude/projects by default. If CLAUDE_CONFIG_DIR is set, Tokenforest reads the projects directory inside that location instead.

The transcript records contain usage fields returned for assistant messages. Tokenforest reads those records without reading meaning from the prompt or response. It keeps counts, timestamps, model names, and a derived project label for the local report.

What each Claude Code token number means

The local report separates five classes:

• Input tokens are uncached tokens sent to the model.
• Output tokens are visible response tokens, with thinking tokens removed when the transcript reports them separately.
• Cache-write tokens are input tokens written to the prompt cache.
• Cache-read tokens are tokens retrieved from that cache.
• Thinking tokens are the model's reported internal reasoning tokens.

This separation matters because some provider totals include one class inside another. Counting an inclusive total and its nested value would count the same work twice. Tokenforest narrows the classes before adding them.

How duplicate entries are handled

Claude Code transcripts can repeat a usage record. Tokenforest deduplicates Claude events by message ID before calculating totals. A repeated record in the same scan should therefore contribute once.

The command also reports how many files and lines it scanned, plus the number of duplicates it skipped. That makes a surprising total easier to investigate.

Raw tokens and weighted tokens answer different questions

Raw counts describe recorded model activity. Tokenforest also calculates a weighted total for its tree-funding progress:

weighted tokens =
  input × 1
  + output × 3
  + cache write × 1.25
  + cache read × 0.02
  + thinking × 3

The weighting is a product rule, not a direct energy or carbon conversion. One tree of progress equals 50,000,000 weighted tokens. Read what token counts can and cannot say about carbon emissions before using the number in environmental reporting.

What stays on your machine

Running the local report does not send prompts, model output, code, tool arguments, file paths, or repository names to Tokenforest.

Account sync is optional. If you connect the CLI, it sends usage counts, model names, sources, and timestamps so the web app can show your forest. The content of your work stays local.

If the total looks wrong

Check these points before comparing reports:

1. Confirm that Claude Code is using the default directory or that CLAUDE_CONFIG_DIR points to the expected location.
2. Use the same date window on both runs. --since 30 means the last 30 days, while no flag scans all available local history for the report.
3. Compare token classes, not just one combined number. Heavy cache use can make the raw total look large while representing repeated context.
4. Review the scan summary for unreadable files or malformed lines.

For Codex, the storage format and deduplication rules differ. See how to check Codex token usage locally.