TokenTopper turns the usage already recorded by Claude Code, Codex, OpenCode, and Gemini CLI into a private local dashboard: annual token run-rate, estimated cost, tier, Professional AI Usage Index, and detailed activity reports. Publish a signed aggregate only when you want a verified leaderboard rank.
npx tokentopper@latestNo account, config file, or API key is required for your local score. See verified TokenTopper ranks.
The default command answers the useful questions first: how much you use coding agents, what that pace costs, and how it compares.
TokenTopper · Professional AI Usage Index
Run-rate 6.33B tokens/yr ($12.1K/yr · 15d observed x365 x1.3)
Tier Operator · Index 53/100 (local estimate)
All-time 200.0M tokens $384.00 1,284 requests, 96 sessions
Window 2026-07-01 → 2026-07-15 · 12 active days
Tools 20 web searches, 10 web fetches
By tool
claude 120.0M $230.40
codex 52.0M $99.84
opencode 18.0M $34.56
gemini 10.0M $19.20
By model
claude-sonnet-4 120.0M $230.40
gpt-5.3-codex 52.0M $99.84
gemini-2.5-pro 10.0M $19.20
Your prompts, responses, source code, file paths, and branch names are never
included in the aggregate. Nothing is uploaded unless you explicitly run
export or sync.
| Need | What you get |
|---|---|
| One view across agents | Claude Code, Codex, OpenCode, and Gemini CLI combined without losing agent/model attribution |
| Understand the bill | Input, output, cache-write, cache-read, and model-aware cost estimates |
| See working rhythm | Daily, weekly, monthly, per-session, and live 5-hour billing-block reports |
| Compare your pace | Annual run-rate, eight tiers, 0–100 Index, and an AI-first benchmark |
| Prove a public rank | Canonical Ed25519-signed aggregate; the private key stays on your machine |
| Automate safely | Machine-readable JSON, signed sync, a read-only MCP server, and an Agent Skill |
TokenTopper runs on Node.js 18 or newer, including the current release line. Node.js 22.13+ is recommended: it is the first release that reads OpenCode's SQLite databases, which hold current OpenCode sessions. Run the current release without installing it:
npx tokentopper@latest # your run-rate, tier, and Index
npx tokentopper@latest export # write a signed.json to upload
npx tokentopper@latest sync # sign and push it automaticallyOr install the CLI globally:
npm install --global tokentopper
tokentopperThe same npm release runs through pnpm, Bun, and Deno. Deno permissions are broad because the CLI discovers local agent logs and can optionally write config or sync over the network:
pnpm dlx tokentopper@latest
bunx tokentopper@latest
deno run -A npm:tokentopper@latestDeno 2.9+ holds newly published dependencies for 24 hours by default. During that
window, wait for the age gate or explicitly run
deno run -A --minimum-dependency-age=0 npm:tokentopper@latest after reviewing the
npm provenance.
Nix users can build and run the repository flake directly:
nix run github:Kalmantic/tokentopperThe calculation API is also prepared for JSR as @openfactoryai/tokentopper;
registry publication requires the JSR scope/package to be linked to this repository.
TokenTopper is a local AI token usage tracker: it tracks Claude token usage (Claude Code), Codex token usage, OpenCode usage, and Gemini CLI usage. It combines coding-agent usage into one comparable score:
- annualized token run-rate and estimated model cost;
- Professional AI Usage Index from 0 to 100;
- eight usage tiers from Curious to Legend;
- daily, weekly, monthly, session, and 5-hour billing-block reports;
- week-over-week/month-over-month deltas plus current and longest active streaks;
- per-model and per-agent breakdowns, nested agent → model with
--by-tool; - a benchmark insight that tells you whether you are ahead of, or falling behind, an AI-first engineer's pace of ~5B tokens/month (~250M per working day);
- optional Ed25519-signed exports for a verified, shareable leaderboard rank — see where you stand globally, by country, and by city.
tokentopper daily
Date Input Output Cache Write Cache Read Total Cost
2026-07-01 3,500 2,800 300 13,000 19,600 $0.16 ▮▮▮▮▮▮▮▮▮▮
2026-07-08 3,000 1,200 50 700 4,950 $0.03 ▮▮▮
─────────────────────────────────────────────────────────────────────────────
Total 6,500 4,000 350 13,700 24,550 $0.19
The active billing block in tokentopper blocks shows a live burn rate and the
projected end-of-window usage, so you can see where the current 5-hour window is
heading before it closes.
Every report ends with an insight that compares your latest month to the benchmark pace, so you always know whether you are pushing your AI tools hard enough — and how to publish your rank if you are:
Insight An AI-first engineer runs ~5.00B tokens/month (~250.0M per working day).
Your 2026-07 pace: 1.2B tokens (24% of benchmark, ~60.0M/workday).
You're falling behind — push your AI tools to the limit and let them work for you.
Rank See where you stand globally, by country, and by city:
tokentopper export → upload at https://openfactoryai.com/tools/tokentopper/
TokenTopper measures historical usage recorded by supported AI coding agents. It is not a prompt tokenizer, context-window calculator, or middleware library.
| Terminal | Status |
|---|---|
| Claude Code | ✅ Supported |
| Codex | ✅ Supported |
| OpenCode | ✅ Supported (SQLite and JSON storage) |
| Gemini CLI | ✅ Supported (current JSONL session records) |
| GitHub Copilot & more | 🛣️ On the roadmap |
Claude Code, Codex, OpenCode, and Gemini CLI are supported today. Other AI coding tools are on the roadmap. One index across every coding agent you use.
Your local Claude Code transcripts in ~/.claude/projects (and
~/.config/claude/projects, or $CLAUDE_CONFIG_DIR) and your Codex sessions in
~/.codex/sessions, plus OpenCode's ~/.local/share/opencode/opencode.db (with
storage/message/**/*.json fallback), and Gemini CLI sessions below
~/.gemini/tmp/*/chats (or $GEMINI_CLI_HOME/.gemini/tmp). It counts tokens
(input, output, cache write, cache read), attributes cost per model, and derives
your run-rate, active days, sessions, and tool calls. More terminals are on the roadmap.
It does not retain or transmit prompt or response content, file paths, or branch
names. Only aggregate counts, model names, and dates are kept, and nothing leaves
your machine until you run export or sync.
tokentopper export writes a tamper-evident signed.json: the aggregate payload
plus an Ed25519 signature over its canonical form, and the public key. The
leaderboard binds your public key to your account on first upload and verifies the
signature on every one, so a rank can't be forged by editing the file after export.
Your private key stays in ~/.tokentopper/key.json.
- Run
npx tokentopper@latestto see your private local score. - Run
npx tokentopper@latest export --prettyto createsigned.json. - Upload it at openfactoryai.com/tools/tokentopper or link once and use
tokentopper sync. - See where you rank globally, by country, and by city — and defend it.
The signature makes the aggregate tamper-evident after export. Publishing is opt-in; local scoring remains private.
For local automation, tokentopper json --pretty prints aggregate usage without a
hostname or machine identifier. Its stable default schema is
tokentopper-summary/1. The additive comparison-ready schema is available with
tokentopper json --schema 2, tokentopper export --schema 2, and opt-in
tokentopper sync --schema 2; it adds signed daily token categories plus nested
agent/model detail without changing the human-readable terminal reports. Sync
continues to default to v1 until the production API migration is complete.
For a copyable Markdown result, run tokentopper share. It includes the
run-rate, tier, local Index, aggregate usage, and agent names, but excludes
session IDs, model names, machine identity, hostnames, and private paths.
| Command | Does |
|---|---|
tokentopper |
Print run-rate, tier, Index, top models (default) |
tokentopper daily |
Per-day tokens (input/output/cache) and cost, with activity bars |
tokentopper weekly |
Per-week report (weeks start Sunday) |
tokentopper monthly |
Per-month report |
tokentopper session |
Per-session report across every supported agent |
tokentopper blocks |
5-hour billing blocks; the active block shows burn rate and an end-of-window projection |
tokentopper json [--pretty] [--schema 1|2] |
Print machine-safe aggregate JSON for scripts |
tokentopper share |
Print a privacy-safe, copyable Markdown score card |
tokentopper export [--out f] [--pretty] [--schema 1|2] |
Write signed.json |
tokentopper sync [--schema 1|2] [--watch] [--interval min] |
Sign and POST to TokenTopper; v1 remains the default |
tokentopper login --token <t> |
Link this machine |
tokentopper skill install |
Install the TokenTopper Agent Skill for Claude, Codex, and Gemini CLI |
tokentopper mcp |
Run a read-only MCP server so agents can query your usage locally |
Every report accepts --since/--until (YYYY-MM-DD or YYYYMMDD), --tool <claude|codex|opencode|gemini> to isolate one agent, --breakdown for per-model
rows, --by-tool for agent rows with each agent's models nested beneath them,
--compact to drop the cache columns on narrow terminals, --no-cost to hide
the cost column, and --json [--pretty] for scriptable output
(tokentopper-report/1 schema with rows and totals). Unlike single-agent
trackers, one report covers Claude Code, Codex, OpenCode, and Gemini CLI
together, and the active billing block includes a live burn rate and projected
end-of-window usage.
tokentopper mcp runs a Model Context Protocol server over stdio so your coding
agent can query your own usage. It is read-only and local-only by design: no
filesystem writes, no network, and it exposes only the same privacy-safe
aggregates the CLI prints — never prompts, file paths, or machine identity.
Register it with a stdio MCP client, e.g. for Claude Code:
claude mcp add tokentopper -- npx tokentopper@latest mcpTools exposed: usage_summary (aggregate totals, run-rate, tier, index) and
usage_report (daily/weekly/monthly/session/blocks rows with totals and the
benchmark insight).
Install one portable, privacy-first Agent Skill into all three assistants:
npx tokentopper@latest skill installUse --claude, --codex, or --gemini for one target, and --force to update an existing
installation. The skill defaults to local inspection and requires explicit consent
before export or upload.
Sign in on the website, create a CLI login command, and run it on every machine you want in the same aggregate. Each installation is bound to its own Ed25519 signing key. The website lets you label devices (for example, Work Mac) or remove them; a later signed sync deliberately re-adds that installation.
Private by default. You only appear on the public leaderboard if you opt in and connect LinkedIn at the site.
Run npm run check to typecheck, test the usage readers, build the CLI, pack the
publishable tarball, install it in an isolated directory, and smoke-test its commands.
The automated release process and recovery steps are documented in
docs/RELEASING.md. Supported distribution channels and
the standalone-executable adoption gate are documented in
docs/DISTRIBUTION.md.
Exact local data formats, privacy boundaries, runtime limitations, and common fixes
are documented in docs/COMPATIBILITY.md.
The signed v1/v2 aggregate contract, comparison formulas, reconciliation rules,
and multi-machine merge semantics are documented in
docs/SCHEMA.md.
The run-rate, Index, tiers, benchmark, pricing limitations, efficiency
eligibility, and UTC period rules are documented in
docs/METHODOLOGY.md.
Growth experiments and the path from useful CLI to repeatable discovery are tracked
in docs/GROWTH.md. Contributions are welcome; start with
CONTRIBUTING.md.
Security issues should be reported privately using the process in
SECURITY.md. The assets, trust boundaries, controls, and residual
risks are documented in docs/THREAT_MODEL.md.
Production health checks and the privacy-safe incident response process are
documented in docs/OPERATIONS.md.
- Check Claude Code token usage locally
- Check Codex CLI token usage locally
- Combine Claude Code, Codex, OpenCode, and Gemini CLI
- Understand cache-read tokens and estimated cost
- Add TokenTopper to an AI development workstation
Usage-reading approach inspired by ccusage (MIT). TokenTopper is a Kalmantic / OpenFactoryAI tool.
If TokenTopper gives you a useful view of your AI coding habits, star the repository and share your verified rank. That is the growth loop.
MIT © Kalmantic