Claude-Cost
Problem Statement
Ever wonder where all your Claude Code tokens actually go? The session logs live on your machine in ~/.claude, but they're a firehose of raw JSON — no spend view, no per-project breakdown, no sense of whether you're lighting money on fire routing Opus work that Sonnet could handle. Existing tools want you to upload your data to a cloud, install a Node toolchain, or hand over an API key.
Solution
Claude-Cost is a local-first dashboard that reads your ~/.claude session logs and turns them into cost estimates, charts, a shareable "Claude Wrapped" card, and ranked advice on how to cut spend. It runs 100% on your own machine:
- No cloud, no telemetry, no API key. It reads local logs and serves the dashboard from a tiny local Python server. Your usage data never leaves your machine
- Zero dependencies. Python's standard library only — no
npm install, no pip requirements.git clone,python3 app.py, open127.0.0.1:5000, done - Refresh in place. Hit ↻ after some Claude Code activity to re-parse and reload — no restart
What's Inside
- ✦ Wrapped — Spotify-Wrapped-but-for-tokens. Headline stats, fun analogies ("Claude wrote ~59 novels of text"), a GitHub-style activity calendar, and a records & superlatives grid (priciest day, marathon session, biggest single message). Export it as a PNG to share
- Overview — spend, sessions, messages, tokens, daily trend, and a real weekday × hour activity heatmap
- Usage — cost + sessions in one place with server-side filters by project and timeframe, so the numbers stay correct, not just the visible rows. Click any session for a turn-by-turn replay with per-turn cost and context-compaction markers
- Activity — where your tokens actually go: most-used tools, a file-hotspots table, skills, and subagents, plus an approximate "context injected" meter (bytes each tool fed back into the conversation — a proxy for tokens, honestly labeled, not a fake per-tool bill)
- Projects — spend grouped by the actual working directory
- Insights — an efficiency grade plus ranked, quantified ways to cut cost (route Opus work to Sonnet, fix cache misses, trim bloated context)
Getting the Numbers Right
Costs are estimates from the token counts in each message's usage, priced with current published Claude rates. A few things it gets right that a naive script wouldn't:
- Dedupes on
message.id. One assistant message is split across many log lines with the same usage repeated on each. Summing per line would multiply your cost by the number of content blocks. It doesn't - Disjoint token buckets, each priced at its own rate: input ×1.0, output ×1.0, cache read ×0.10, cache write 5m ×1.25, cache write 1h ×2.0
- Local time for daily and hourly buckets (logs are UTC). Unknown and
<synthetic>models don't get silently priced at $0 - Raw buckets, never a frozen dollar figure. The warehouse stores token counts, not computed cost, so editing a rate in
pricing.pyre-prices all your history the next time you load — even sessions whose logs are long gone
History That Outlives the Logs
Claude Code prunes its own ~/.claude session logs after about 30 days. Claude-Cost keeps a tiny local warehouse at ~/.claude-cost/history.db (a SQLite file) so your spend history sticks around after the raw logs disappear.
- Persistent — each message is ingested once, keyed on its stable id. When a log file gets pruned, its rows stay in the warehouse, so your all-time totals don't quietly shrink
- Incremental — only session files whose size or mtime changed get re-parsed, so after the first run the dashboard warm-starts in about half a second instead of re-reading hundreds of MB every time
- Yours — it lives outside the repo and never leaves your machine. Point it elsewhere with
--dbor$CLAUDE_COST_DB, or delete it to rebuild from whatever logs still exist