Command line · macOS, Linux, Windows
One command to read your usage
Your tools already wrote down everything they did. Nobody reads it, because it is scattered across a dozen folders in a dozen formats. One command turns all of it into reports of recorded usage by tool, model, project, and session, with estimated API list-rate value. Local reports need no account. Setup fetches reference prices and configures collection.
$ curl -fsSL https://tokenstat.ai/install.sh | bashGetting an answer
Scan once, then read the archive
Run a scan to collect local usage records, then open the report. Other reports read the collected archive. Typing tokenstat on its own opens the full-screen view and refreshes itself if the archive has not been scanned for more than ten minutes.
$ tokenstat scan $ tokenstat
Filters apply everywhere: --since, --until, --last N, --model, --project. Every command takes --json.
Reference
Ask the question you have
| Command | Shows |
|---|---|
| tokenstat | Full-screen interactive client, with tabs, headline stats, and a command field |
| summary | Headline numbers, the activity grid, and the model breakdown |
| heatmap | The activity heatmap on its own |
| daily · weekly · monthly | Usage per day, ISO week, or month |
| models · projects · sessions | The three breakdowns. models --detail adds context window, capabilities, and benchmark scores |
| blocks | Usage in five-hour windows, the shape Claude-style rate limits use |
| wrapped | A year in review, built from the local archive |
| budget | Soft caps on list-rate equivalent value, daily or monthly. Advisory, never a charge |
| statusline | One line for a shell prompt or an editor status bar. Reads the archive only, so it stays fast |
| export | CSV or JSON of the events themselves, counters and ids only |
| doctor | Archive health, and a reconciliation against Claude Code's own rollup |
| scan | Read new data from your tools into the archive. Everything else reads that archive |
| setup | Scan, schedule, and optionally connect an account, in one pass. Safe to run again |
| schedule | Install the automatic scan, sync, and update entries for this platform |
| pricing · catalog · plans | The local list-rate, model, and subscription snapshots, refreshed on request |
| auth · fetch | Vendor credentials and remote usage, for the sources that cannot be read off disk |
| login · device · sync · logout | Link this machine to an account and upload sealed aggregates. Opt in |
| update | Check or apply a newer release, verified against the release checksums |
| mcp | Usage queries and task, automation, and workflow tools over stdio |
| host | Install, inspect, and manage an always-on host on Linux or macOS |
The help center has the longer version: which command shows what.
tokenstat models prints, tab 5 of the same client.Preserve your history
Keep usage history as you work
Claude Code removes transcripts after 30 days by default. Scheduled scans preserve their counters before that happens. Older rollups can recover some totals, but do not restore every session detail.
A scan also makes one archive backup per day and keeps seven copies. tokenstat doctor reports their count and size. Backups rotate. Restoring one is a manual action.
Scanning and update settings → · Run an always-on host on Linux or macOS →