Claude Code Usage Report (Free)

See what your Claude Code usage adds up to: tokens and API-equivalent cost by day, month, project, model, session and 5-hour window, straight from the logs Claude Code already writes on your machine.

• One Python file, standard library only (Python 3.9+). No install, no account, no network. Nothing leaves your machine.
• Reads ~/.config/claude/projects and ~/.claude/projects, or the folders in CLAUDE_CONFIG_DIR (comma-separated), or --dir.
• Prices from Anthropic's pricing page (checked 2026-11-10): 5-minute and 1-hour cache writes, cache reads, fast mode, the Haiku 5.5 over-100k-token tier, and the lower cache-read rates on Fable 5.x, Mythos 5.x, Opus 5.5 and Sonnet 5.5.

python3 usage_report.py                       # last 7 days, by day
python3 usage_report.py monthly
python3 usage_report.py projects --since 2026-10-01
python3 usage_report.py models
python3 usage_report.py sessions --limit 10
python3 usage_report.py blocks                # 5-hour windows, like Claude Code's usage limits
python3 usage_report.py daily --tz America/New_York --compact
python3 usage_report.py daily --json          # or --csv, --md (paste into a PR or notes)
python3 usage_report.py models --project webshop

Try it on the bundled sample logs first: ./demo.sh.

It is what the same tokens would cost at Anthropic API list prices. If you are on a Pro or Max plan you pay the subscription, not this number. It is still the best way to see which projects, models and sessions use the most, and whether a plan is worth it.

• Claude Code writes several copies of a streamed reply. Lines with the same message id and request id are counted once (the most complete copy is kept).
• <synthetic> and API-error lines are skipped. Lines that are not valid JSON are skipped.
• A cost recorded in the log (costUSD) is used as is. Otherwise the cost comes from the price table at the top of usage_report.py.
• Models with no published price (for example old Claude 3.x ids) are counted in tokens but not priced; totals then show *.
• Days and windows use your local time zone, or --tz.
• 5-hour windows start at the hour of the first message and close after 5 hours (a new window also starts after a 5-hour gap).

./run_tests.sh runs 21 tests on sample logs: costs worked out by hand for every price rule, de-duplication, skipped lines, time zones, date filters, all six reports, JSON/CSV/Markdown output and the CLI's error messages. Tested on Python 3.13 and 3.10.

• Prices change. They live in one table at the top of the file with the date they were checked; update it when Anthropic changes them.
• It does not price the US-only inference multiplier, Batch API discounts, or server-tool fees such as web search.
• Claude Code's log format is not a public API and may change.
• It shows API-equivalent cost, not your remaining plan limit.