tokenspend

The worldwide AI token spend leaderboard. Compete with vibecoders across the globe: https://tokenspend.fyi

The whole client is one file

bin/tokenspend.js — zero dependencies, readable in a few minutes. That's the point: you can see exactly what it does before you run it.

Install

npx tokenspend-cli init

(the npm package is tokenspend-cli — the unscoped name was blocked by npm's similarity filter; the command after install is just tokenspend)

Logs you in with GitHub (device flow, 30 seconds; or --anon to stay anonymous), lets you pick what to collect (interactive checkboxes), installs the auto-submit hook and offers a full-history backfill. tokenspend remove uninstalls everything cleanly.

Self-updating (since 0.3.8): the hook runs tokenspend-cli@latest, so every session end picks up the newest published version (offline it falls back to the cached one). Machines that installed earlier are pinned by the npx cache — run npx -y tokenspend-cli@latest submit once and the hook migrates itself.

Refreshes inside long sessions (since 0.3.9): session end is not a reliable moment — a killed terminal or a reboot never fires it, and a session left open for a week never ends at all. Both leave the board a day behind, and they tilt it: short-session users are counted the same day, long-session users always trail. So init also adds a Stop hook that submits once an hour while you work, over a two-day window (about a second of CPU and 0.5 GB on a heavy machine, where a full 30-day submit costs 21 s and 2.5 GB — the read is the whole cost, and the window is what bounds it). Almost every invocation is a timestamp check: no node, no network, ~9 ms. Every fourth hour the same submit goes through @latest, which is also how the client updates itself; the hourly runs use the path that update left on disk, because npx caches by spec string and a bare spec would freeze on one version forever.

No background service is installed — no launchd, no systemd, no scheduled task, nothing that outlives the package. Both hooks live in settings.json and tokenspend remove takes both out. POSIX only for now; on Windows submits still happen at session end. tokenspend status shows both halves and when each last ran.

Sources

| source | how it's read | auto-submit | |---|---|---| | Claude Code | local session logs | yes — hourly while you work, plus a submit when the session ends | | Codex CLI | local rollout files | rides along: every submit covers all sources | | opencode | local SQLite storage (recent versions; read-only) | rides along | | Gemini CLI, Cursor | coming | — |

Every submit aggregates all detected sources on the machine. No Claude Code on the machine (Codex/opencode only): run tokenspend submit manually or from your own cron — the hook has nothing to attach to yet.

What is collected — and how to turn each thing off

Everything the client sends is a daily aggregate. Never prompts, never code, never file paths, project or repo names, never your IP. One exception exists, and you turn it on yourself: attribution (see below) sends repo slugs, branch names and commit SHAs for your team's private spend-to-PR page.

| data | why | turn off | what happens to stored data | |---|---|---|---| | date, source, token counts (input / output / cache read / cache write) | this IS the leaderboard | — (core, not collectable separately from the product) | tokenspend delete-account erases everything server-side | | model names (e.g. which models you burn most) | model-mix stats on your profile | tokenspend config models off | next submit --all rewrites history with models collapsed to hidden | | sessions per day | sessions column on the board | tokenspend config sessions off | next submit --all rewrites history with 0 | | billing mode + plan tier (subscription / API, Max tier) | league split on the board | tokenspend config billing off | next submit --all overwrites stored values with blank | | provider account age | honest "vibecoding since" (local logs rotate) | tokenspend config age off | erased server-side on next submit | | timezone + country | flag on the board, "vibecoded from" on your profile. Country is derived server-side from the request (via Cloudflare) — country code only, IP and city are never stored | tokenspend config geo off | erased server-side immediately on next submit | | subscription windows: how full your 5h / 7d limits are, when they reset, plan tier, when the plan renews — the plan is identified by a hash of the provider account, so the email never leaves the machine, and neither does the OAuth token used to read it | your private subscriptions page: which plan idles, which hits the ceiling, so paid-for windows stop expiring unused. Never on any public board | tokenspend config limits off | tokenspend delete-account erases everything | | attribution (off by default): GitHub repo slug, branch, commit SHAs made during the session + per-session token counts | your team's private engineering page — spend matched to pull requests, visible only to signed-in team members, and only for repos the team's GitHub App covers. Prompts, code, diffs, file paths never leave the machine | tokenspend config attribution off (limit capture: tokenspend config repos owner/a,owner/b) | tokenspend delete-account erases everything |

• tokenspend init shows this list as interactive checkboxes (space to toggle, enter to confirm) — nothing is collected before you confirm. tokenspend config reopens the same checkboxes anytime; flags --no-geo, --no-billing, --no-age, --no-sessions, --no-models do the same non-interactively.
• tokenspend status prints locally what would be sent, before anything leaves the machine. tokenspend limits prints the subscription reading itself.
• Team plans (/t/<slug>/plans, members only): the same rows for the whole crew, so rotation — move work off the plan pinned at the ceiling, onto the one idling — is a decision someone can actually make. Each plan is shared with your team by default and hidden again with one checkbox on /subs; nothing here ever reaches a public board.
• Subscriptions page (/subs, private, sign-in required): a row per plan — 5h and 7d fill right now, the peak each weekly window reached, when the window resets, when the plan renews, and a name you give it yourself ("me", "bots") over its generated code. Tokens say what you spent; only the window says what you wasted. The page also shows the gap between the windows and the spend the client can account for — bots on a proxy and machines without the client burn the plan invisibly, and that difference is the honest measure of it.
• The append-only submission journal on the server retains what past submissions contained (audit / anti-abuse), except geo and account age, which are erased on opt-out as described above.

Attribution (opt-in, for teams)

tokenspend config attribution on switches the machine into extended mode: at the end of every Claude Code session the hook records which GitHub repo, which branch and which commit SHAs the session produced, plus that session's token counts per model. Your team's captain connects a read-only GitHub App (pull requests + repo list) to the team, and the team page grows a private engineering tab: spend matched to pull requests — shipped / in flight / never shipped.

• Default is off. Nothing changes for existing users.
• Only repos with a GitHub remote are captured; limit further with tokenspend config repos owner/a,owner/b.
• The team sees sessions only for repos its GitHub App covers — your side projects stay invisible even with attribution on.
• The engineering page is visible only to signed-in team members. It never appears on public boards.

Commands

tokenspend init      # GitHub login (or --anon), hook install, backfill offer
tokenspend login     # claim your GitHub handle later — history carries over
tokenspend submit    # last 30 days (--all = full history)
tokenspend config    # collection toggles: geo, billing, age, sessions, models, attribution
tokenspend limits    # this machine's plan: 5h / 7d windows, resets, renewal
tokenspend status    # what's configured and what would be sent
tokenspend remove    # uninstall both hooks + delete local config
tokenspend delete-account  # erase your account and ALL its data server-side

License

FSL-1.1-MIT (Functional Source License) from 0.3.0 onward: read it, run it, modify it, use it inside your company — anything except offering a competing commercial product. Each release automatically becomes plain MIT two years after it ships. Versions up to and including 0.2.0 remain MIT forever.