tokenstat is the CLI for tokenstat.ai. It reads the
local session logs your tools already write, normalizes counters into one schema,
and reports spend by model, project, tool, and time. Everything runs on your
machine by default. Sync to a public profile is opt in.
See what a synced profile looks like: tokenstat.ai/gyorgy
- Local first — counters stay on your machine; conversation text never reaches the archive
- Many sources — Claude Code, Codex, Grok, OpenCode, Cline, Antigravity, OpenClaw, Zed, Copilot CLI, plus Cursor fetch
- One schema — daily, weekly, monthly, and per-model views across every tool
- Activity heatmap — rolling calendar with streaks, busiest day, and a purple-to-cyan ramp
- Model catalog — context window, capabilities, and public benchmark scores per model
- Optional sync — sealed aggregates to
tokenstat.ai/<handle>when you link an account (live example) - Self-update — verified GitHub Releases with rollback if the new binary cannot run
| Kind | Tools |
|---|---|
| On disk | Claude Code (with rollup recovery), Codex, Grok, OpenCode, Cline, Antigravity CLI, OpenClaw, Zed, Copilot CLI |
| Remote fetch | Cursor (keychain or pasted token, 30 minute cache) |
| IDE sync | Antigravity IDE (app open, then tokenstat fetch) |
Plan quota for Antigravity is reported separately and is never turned into fake token events.
The website is a separate project. This repository is the CLI, shared core, and MCP server.
crates/
tokenstat-core/ Parsing, normalization, pricing, aggregation. No network.
tokenstat-cli/ Command line front end.
tokenstat-sync/ The only crate that talks to the network.
tokenstat-mcp/ MCP server over the core facade.
Keeping logic in tokenstat-core means every front end shares one implementation.
The split is also what makes the privacy claim structural: the crate that reads
your logs has no way to send them anywhere, because it does not link a network
stack at all.
Website one-liners (recommended). They download the matching GitHub Release
binary into a user-writable path (~/.local/bin on macOS/Linux,
%LOCALAPPDATA%\tokenstat on Windows), verify SHA256SUMS, and run
tokenstat setup (scan, hourly schedule, and an account prompt on a TTY).
Self-update (tokenstat update) needs that user-writable path; system prefixes
like /usr/local/bin are refused.
# macOS / Linux
curl -fsSL https://tokenstat.ai/install.sh | bash# Windows (PowerShell)
irm https://tokenstat.ai/install.ps1 | iexThe scripts in this repo (scripts/install.sh,
scripts/install.ps1) are the source of truth. The
website should proxy or copy them so the one-liners stay in sync. Opt out of the
schedule with --no-schedule (Unix) or TOKENSTAT_NO_SCHEDULE=1.
Release builds are published on GitHub Releases for macOS (Apple silicon and Intel), Windows, and Linux.
tokenstat setup # scan, schedule, and offer to connect an account
tokenstat update --check
tokenstat updatesetup is safe to re-run. One confirmation at the start on a TTY, then it gets
on with it. Piped or scripted runs (including the install scripts) proceed with
defaults without --yes. --local-only skips the account step,
--no-schedule skips the hourly scan install, and --code WXYZ-1234 connects
using a code from tokenstat.ai/link. A linked
account publishes a page like tokenstat.ai/gyorgy.
update verifies SHA256SUMS, runs the downloaded binary to confirm
--version and --help, then swaps it in. The old binary is moved aside and
restored if the new one cannot run from its final path.
Automatic daily updates are on by default after setup / schedule install.
They still verify checksum and run the new binary before replacing this one.
Opt out:
tokenstat update --auto offmacOS builds are Developer ID signed and notarized when repository secrets are
configured (see CONTRIBUTING.md). After a website install,
~/.local/bin/tokenstat is that release: do not overwrite it with a local
cargo build, and do not ad-hoc codesign --sign - it (that strips the
Developer ID signature). Scheduler entries prefer the signed install when both
a release and a cargo binary are present. When the installed binary carries a
real signing identity, a replacement must too.
From source:
cargo install --path crates/tokenstat-cli# macOS / Linux
curl -fsSL https://tokenstat.ai/uninstall.sh | bash
curl -fsSL https://tokenstat.ai/uninstall.sh | bash -s -- --purge --yes # also delete archive# Windows
irm https://tokenstat.ai/uninstall.ps1 | iex
$env:TOKENSTAT_PURGE="1"; $env:TOKENSTAT_YES="1"; irm https://tokenstat.ai/uninstall.ps1 | iexSee scripts/uninstall.sh and
scripts/uninstall.ps1. They remove the schedule
first, then the binary. The archive is left alone unless you pass
--purge / TOKENSTAT_PURGE=1.
| Platform | Data directory |
|---|---|
| macOS | ~/Library/Application Support/ai.tokenstat.tokenstat |
| Linux | ~/.local/share/tokenstat |
| Windows | %APPDATA%\tokenstat\tokenstat\data |
Removing the local install does not delete a hosted profile. Export or delete the account from the website settings if you made one.
tokenstat scan
tokenstatscan reads your logs into a local archive. Everything else reads that archive.
Bare tokenstat on a TTY opens a full-screen client with tabs, headline stats,
and a command field. If the archive was last scanned more than 10 minutes ago,
it rescans automatically on open. Piped use and tokenstat summary print the
one-shot report.
| Command | Shows |
|---|---|
tokenstat |
Full-screen interactive client (TTY) |
tokenstat summary |
Headline numbers, activity grid, model breakdown |
tokenstat heatmap |
Activity heatmap (JSON contract for the website profile) |
tokenstat wrapped |
Year-in-review from the local archive |
tokenstat daily / weekly / monthly |
Usage per day, ISO week, or month |
tokenstat models / projects / sessions |
Breakdowns |
tokenstat models --detail |
Per model, with context window, capabilities, and benchmark scores |
tokenstat blocks |
Five-hour usage windows |
tokenstat budget |
Soft list-rate caps (--daily / --monthly) |
tokenstat export |
CSV or JSON dump of events |
tokenstat auth / fetch |
Vendor tokens and remote usage |
tokenstat pricing |
Local list-rate snapshot (--refresh to fetch) |
tokenstat catalog |
Local model catalog and plans snapshot (--refresh to fetch) |
tokenstat plans |
Subscription plan prices next to your own list-rate equivalent |
tokenstat mcp |
MCP server over stdio |
tokenstat doctor |
Archive health and reconciliation |
tokenstat statusline |
One line for a shell prompt |
tokenstat setup |
Scan, schedule, and optionally connect an account |
tokenstat schedule |
Automatic scanning, syncing, and updates |
tokenstat update |
Check or apply a newer release build |
tokenstat login / sync |
Link this machine and upload sealed aggregates |
Filters: --since, --until, --last N, --model, --project. Every command
accepts --json.
List rates are not shipped in the binary. tokenstat setup fetches them, or run
tokenstat pricing --refresh and tokenstat catalog --refresh yourself. Both
land in your local data directory and are read offline from then on.
The two snapshots answer different questions and are kept apart on purpose. The
price book is published list rates, and a figure taken from it is printed plain.
The catalog carries provider offers, which is what lets a model the price book
has never heard of still show a number: those are marked ~ and are never
presented as a list rate.
Terminals that cannot do 24-bit colour fall back to the 256-colour palette, and
a non-UTF-8 locale swaps the box drawing and block characters for ASCII. Force
the plain rendering with TOKENSTAT_ASCII=1.
Claude Code deletes transcripts after 30 days by default. Install the hourly scan before you need the numbers, not after.
tokenstat schedule --installwrites the scheduler entry for your platform. The website installer runs
tokenstat setup, which installs the scan schedule by default.
With an account linked, a sync entry uploads on your plan interval (60 / 30 / 10 minutes). A daily update check (on by default) runs with jitter and verifies the new binary before replacing the running one.
Requires a recent stable Rust toolchain (rust-toolchain.toml).
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo build --releaseEverything happens on your machine. tokenstat reads your local session logs,
extracts token counters, and discards the rest. Only aggregate numbers are ever
eligible for sync, and the source is open so you can confirm it.
- Session logs contain prompts and code. Counting tokens means opening those files. The guarantee is the boundary: conversation text is dropped at the parser and never reaches the local database.
- Local reports show real project names and models. Only the sync payload uses salted hashes, and the salt never leaves.
- The sync payload holds dates, counts, model ids, and opaque keys. No paths,
prompts, or hostnames.
tokenstat sync --dry-runprints the exact bytes.
The core library cannot link a network stack, enforced in CI.
See CONTRIBUTING.md for the branching model, commit message format, and release steps.
GPL-3.0. See LICENSE.
The CLI and the core library stay open source. Forks and modifications are welcome and must remain under the same license, so nobody can turn this into a closed source paid product. The hosted profile service is a separate project.
The name is not part of that grant. "tokenstat" and the tokenstat logo are trademarks of pueev OÜ, reserved under section 7(e) of the GPL. Fork the code freely, but give your version its own name so users can tell whose build they are running. See TRADEMARK.md.
The iPhone and iPad clients are published by pueev OÜ under separate terms, not under the GPL.
That is not a second, better version being held back. App store terms restrict how many devices a copy may be used on and forbid recipients from redistributing it, and the GPL does not let a distributor add restrictions like that. So a GPL build cannot be conveyed through an app store at all. pueev OÜ can publish one of its own code, because a copyright holder is not bound by the license it grants to others.
Everything the mobile clients are built on is in this repository under the GPL.
This repository does not accept pull requests, so that pueev OÜ remains the sole copyright holder and can keep shipping the applications. Issues are very welcome and are the more useful thing anyway: a harness that is not read yet, counts that disagree with the tool itself, or anything in the privacy claim that does not match the code. See CONTRIBUTING.md.