Tokenfatty sits in your menu bar and reads the session transcripts Claude Code already writes to your disk. No API key, no account, no configuration. It sends nothing anywhere and costs zero tokens to run.
Real output from one machine over three days. Project names changed.
Claude Code is a subscription, so you are never billed per token. Tokenfatty reports notional value instead: what the same tokens would have cost at public API list rates. It is not a bill. It is what the subscription delivered, priced against the alternative.
Every response reports four disjoint token buckets, each priced differently. Cache writes cost more than fresh input; cache reads cost a tenth. The call that builds context pays for it, and every call after rides cheaply on what it stored.
| Token bucket | Rate $/Mtok | Tokens | Cost | Share |
|---|---|---|---|---|
| Uncached input | 5.00 | 268 | $0.00 | 0.0% |
| Cache write — 1.25× base | 6.25 | 1,460,586 | $9.13 | 30.4% |
| Cache read — 0.10× base | 0.50 | 29,990,344 | $15.00 | 49.9% |
| Output | 25.00 | 236,290 | $5.91 | 19.7% |
| Total | 31,687,488 | $30.03 |
Cache reads are half the cost despite being the cheapest bucket, purely on volume. That is the kind of thing you cannot see without a meter.
curl -L https://tokenfatty.com/tokenfatty.tar.gz | tar xz
cd tokenfatty86 KB. Read install/install.sh
before you run it — it is 118 lines and it tells you every path it
touches.
./install/install.shIt builds ~/Applications/Tokenfatty.app
and registers a login agent, so the meter starts with your machine and
restarts if it dies. It checks for PyObjC and asks before installing
it — never silently.
A small round kid and today's figure appear top right. Click for the breakdown. It refreshes every 30 seconds.
python3 --version works, you are set./install/uninstall.shDeletes the app, the login agent and the log — exactly the three paths the installer created, and nothing else. It leaves PyObjC alone, since that went into your Python environment and something else may want it.
The menu bar meter answers “what am I spending right now”. The same download also generates a full report, which answers the questions the meter cannot: which project spent it, which responses were expensive, and how much of this week’s plan is left.
python3 -m tokenfatty.cli --source claude-code-local --out usage.htmlOne self-contained HTML file with no external resources of any kind — no fonts, no scripts, no analytics. It opens on a laptop with the network off, and it is yours to delete.
The session and weekly windows are reconstructed exactly from your transcripts, and so is what you spent inside them. The allowance behind the percentage is the one thing no local tool can see — it is not published and it is not on your disk. So it is not guessed. You read your own figures off your account page once and they are back-solved:
python3 -m tokenfatty.cli --source claude-code-local \
--week-reset 'Fri 06:00' --week-pct 27 --session-pct 35 \
--product-mix 'Claude Code=94,Chats=6' --save-limits --out usage.htmlEvery value on that line is printed on your account page.
--save-limits stores the derived allowance, so later
runs need none of it. The reading itself is never stored: a percentage is true
at the instant it was taken, and re-applying yesterday’s to today would
back-solve a different allowance every run and call it a measurement.
Skip all of it and the report still renders every measured figure — it simply has no percentages, which is the correct output rather than a degraded one.
There is no HTTP client, no SDK and no API key anywhere in the codebase.
The reader imports four standard-library modules:
datetime, glob,
json, os. It opens files
under ~/.claude/projects and does arithmetic.
If this ever changes it will be stated here before a release that changes it, not after. A tool distributed as local-only that quietly starts reporting home is the one mistake that would deserve to end it.
Claude Code writes one transcript record per content block, but token usage is reported per response. A reply containing a thinking block, some text and three tool calls becomes five records, each repeating identical counts. Tokenfatty collapses them on message id.
Counting records instead of responses overstates spend by a multiple — on the run above, 265 duplicate records collapsed into 134 real responses. Every figure the app shows names the files it came from and how many records were read, so you can check it.