claude-usage

Report Claude Code token usage from local logs.

Anthropic doesn't expose a lifetime token counter to subscribers — but Claude Code writes detailed per-session JSONL logs under ~/.claude/projects/. This tool reads those logs and aggregates the numbers.

Single-file Python, stdlib only, no dependencies.

Install

curl -L https://raw.githubusercontent.com/Horizon-Digital-Engineering/claude-usage/main/claude-usage \
  -o ~/.local/bin/claude-usage && chmod +x ~/.local/bin/claude-usage

Make sure ~/.local/bin is on your PATH. Requires Python 3.9+.

Or just clone and run:

git clone https://github.com/Horizon-Digital-Engineering/claude-usage
./claude-usage/claude-usage

Usage

claude-usage                          # last 365 days, text report
claude-usage --lifetime               # everything
claude-usage --days 30                # last 30 days
claude-usage --by-project             # add per-project breakdown
claude-usage --format json            # JSON to stdout
claude-usage --format csv > out.csv   # CSV to stdout

Example output

============================================================================
  Claude Code token usage · LIFETIME
  2026-01-15 → 2026-05-12  (118 days of activity)
  17,330,660,900 tokens  (17.3 B)
  45,756 entries across 438 files  ·  56,447 skipped
============================================================================

GRAND TOTAL
  Input tokens                     1,684,815
  Output tokens                   23,070,908
  Cache creation                 234,220,561
  Cache read                  17,071,684,616
  --------------------- --------------------
  Total                       17,330,660,900

BY MODEL
  Model                                                          Total
  claude-opus-4-7                                       10,622,203,942
  claude-opus-4-6                                        6,435,057,304
  claude-haiku-4-5-20251001                                247,190,365
  ...

What gets counted

For every JSON line in every .jsonl file, the tool reads:

• timestamp (ISO-8601)
• message.model
• message.usage.{input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens}

Lines without a usage block (user messages, tool results, system events) are counted toward skipped — that's normal. Malformed JSON is also skipped silently.

License

MIT