Claude Code can tell you what the session in front of you has cost. It cannot tell you what a project has cost across a month — and if you work on a laptop and a desktop, it cannot add the two together. Token DB reads the transcripts already sitting on each machine and answers both.
One command — macOS, in Terminal:
curl -fsSL https://tokendb.app/install.sh | shWindows, in PowerShell:
irm https://tokendb.app/install.ps1 | iexFree while it is in beta · macOS and Windows · Usage metadata only
Usage is reported per account, per billing period. Your work is not organised that way — it is organised in folders, and the one that quietly doubled last month looks exactly like the one that did not. Nothing on your machine adds a project up.
Claude Code keeps its transcripts locally, so a laptop knows only what the laptop did. Work across a personal Mac, a work Mac and a Windows desktop and there is no view that contains all three — only three partial answers you cannot add up.
The data exists. It is already on disk, written by Claude Code itself, and nothing reads it. Token DB does — every machine reporting into one account, from the first day you have history for.
Claude Code writes a transcript of every session, and each assistant message carries its own token counts. The recorder tails those files. It does not wrap the CLI, install hooks, or intercept anything — so it keeps working across Claude Code updates, and it can read your history from before you installed it.
Per message: token counts, the model, a timestamp, the project folder name and the git branch — plus the identifiers that let the portal deduplicate and group what it is given (a message id, a session id, and a one-way salted hash of the project path, never the path itself), your Claude Code version, which service tier answered, and whether the turn was a sub-agent's rather than yours.
Once per session it also sends what that session loaded before you typed anything: how many tools and skills were offered, how many were used, how many times each block was re-emitted, the size in bytes of each of those blocks, the names of your MCP servers, and the names of your skills — each one with where it came from (yours, a plugin's, or one Claude Code ships) and whether you invoked it in that session. The counts travel too: how many skills were listed and how many you used, split the same three ways. That is the whole list.
Those names are what make "you load this one into every session and never call it"
actionable rather than a percentage. If a name is itself confidential — a client's
name, an unannounced project, a skill you wrote called
acme-billing-migration — set TOKREC_UPLOAD_NAMES=0 before
the recorder starts. One setting covers both: no server name and no skill name then
leaves the machine, and neither does the per-server size, which means nothing without
a name to attach it to. Every other count still travels, so the portal can still tell
you how much you load and how little you use; it just cannot tell you which one to
remove.
There is no field in either upload format capable of carrying a prompt, a reply, a
file, or the text of a skill — and tokrec watch --dry-run prints exactly
what would be sent, both kinds, before you send anything.
Four views, one question each: is my spend growing, which project is burning it, which models cost what, and which machines are reporting. Cache reads are shown apart from input tokens, because they are billed at about a tenth of the rate and folding them together makes a cheap project look expensive.
The recorder opens transcript files for reading and maps them onto a fixed set of fields, by hand, one at a time. A new field appearing in a future Claude Code release cannot start being uploaded by accident — there is nowhere for it to go. The same applies to the once-per-session record: a skill's body, an MCP server's instruction block and a memory file are each reduced to a byte count at the moment they are read, and the text is gone before anything is assembled to upload. A skill's name travels; what is written inside it never does.
Signing in from the terminal prints a code you approve in the browser. The device gets a write-only token, kept in the macOS Keychain or Windows Credential Manager, that can append your usage and nothing else: it cannot read your data, list your other machines, or change your account. Revoke it from the portal and it stops on its next request.
A day with no data is drawn as a gap, never as a zero, because "you did not use Claude Code" and "the recorder was not running" are different facts and Token DB cannot tell them apart. Costs are labelled estimates, with the date of the rate that produced them. A model with no price shows a dash, not $0.00.
One command. Your existing history uploads on the first run, so the charts have something in them before you write another prompt.