Tokens

---

You already burn tokens all day. tokens.ci turns that into a public standing: how much you ran through today, how it splits across clients and models, and where you rank against everyone else doing the same thing.

bunx tokens-cli@latest login

iOS app

Your rank and usage on your phone, without opening a browser — share cards rendered on device, plus Home screen and Lock screen widgets for the day's tokens, your running total and your rank.

There is no sign-in. You enter a GitHub username and the app reads that public profile, so enter your own or the widgets will show someone else's usage.

Why this repository is public

So you can check what we send.

The CLI reads the session files your AI clients already write to disk, totals them locally, and uploads only the totals — token counts, model names, client names, timestamps. Prompts, completions, file contents and paths never leave your machine.

You do not have to take that on faith. The whole pipeline is here:

• cli/tokens-core/src/sessions/ — one parser per client, showing exactly which fields are read out of each session file
• cli/tokens-core/src/aggregator.rs — how those reads become daily totals
• cli/tokens-cli/src/commands/ — the submit path, including the exact payload

tokens submit --dry-run prints what would be uploaded without uploading it.

If your gateway adds routing prefixes to model IDs, list those prefixes in ~/.config/tokens/settings.json (or $TOKENS_CONFIG_DIR/settings.json):

{
  "modelIdPrefixesToStrip": ["gateway-a/", "gateway-b/"]
}

This list is empty by default. Matching is case-insensitive; the longest matching prefix is removed once before the existing model normalization. Empty prefixes are ignored, and removal cannot produce an empty ID. Unlisted namespaces remain distinct. The rule affects local grouping and uploaded model IDs, unlike the presentation-only modelAliases setting. Pricing, token counts, costs, and raw session files and caches are unchanged. Subsequent submissions apply the rule to historical usage too. Use the same rules on devices that submit the same usage; changing the rules changes uploaded model identity.

We are not asking anyone to run their own copy. This repo exists to be read.

Supported clients

All 42 are detected automatically — if it is installed and has written sessions, it is counted.

Amp	Antigravity	Antigravity CLI	Claude Code
Cline	CodeBuddy	Codebuff	Codex CLI
Command Code	Copilot	Crush	Cursor
Devin CLI	Devin Desktop	Droid	Fx
Gemini CLI	Goose	Grok Build	Hermes Agent
Jcode	Junie	Kilo	Kilo CLI
Kimi	Kiro	MiMo Code	Mux
OpenClaw	OpenCode	OpenCodeReview	Orca
Pi	Qwen	Reasonix	Roo Code
Paseo	Trae
Warp	WorkBuddy	ZCode	Zed Agent

Client	Data location
Claude Code	~/.claude/projects/, ~/.claude/transcripts/
Codex CLI	~/.codex/sessions/
OpenCode	~/.local/share/opencode/opencode.db (1.2+) or ~/.local/share/opencode/storage/message/
Cursor	API export cached at ~/.config/tokens/cursor-cache/usage*.csv
Copilot CLI	~/.copilot/otel/*.jsonl
Gemini CLI	~/.gemini/tmp/*/chats/*.json
Kimi CLI	~/.kimi/sessions/
Qwen CLI	~/.qwen/projects/
Reasonix	~/.reasonix/stats/*.jsonl (override via REASONIX_STATE_HOME or REASONIX_HOME)
Amp	~/.local/share/amp/threads/
Droid	~/.factory/sessions/
Cline	VS Code globalStorage tasks, or for the Cline CLI / desktop

Paseo

Paseo runs agents through their native providers. Usage is reported under the underlying supported client (for example, Claude Code or Codex CLI), including sessions launched from Paseo.

For Claude and Codex profiles with separate data directories, Tokens also reads agents.providers in ~/.paseo/config.json (or $PASEO_HOME/config.json). It finds absolute env.CLAUDE_CONFIG_DIR and env.CODEX_HOME paths on built-in providers and profiles that extends them, including inherited base settings. Claude projects, subagents and transcripts, plus active and archived Codex sessions, use the existing parsers and file deduplication. Paseo's agent records and timelines are not counted again.

Run Tokens on the daemon host, where the session files live. Relative provider paths and paths set only in the daemon's launch environment cannot be discovered from this config; use absolute provider paths or Tokens' existing scanner.extraScanPaths setting for those installations.

Clients that expose usage only through an account API need a sync step first — tokens cursor sync, tokens antigravity sync, tokens trae sync, tokens warp sync — after which they submit like everything else.

Pricing comes from a combination of LiteLLM, OpenRouter and models.dev, with the best matching rate used per model. Built-in overrides handle tiered rates and cache discounts where the upstream feeds do not.

What makes it different

One number, across everything. Most usage tools are scoped to a single client. This one merges every client you run into one total, deduplicated per client-day, so switching from Claude Code to Codex mid-afternoon does not split your day into two half-stories.

Built to be gamed against. A public leaderboard attracts inflated numbers. Submissions are checked for cross-device duplicates and monotonic regressions, accounts caught faking totals are banned, and the bans are public in the Hall of Shame. Ranking is worth nothing if nobody polices it.

A profile worth linking. Your page carries a verified badge if your GitHub account has at least two social links, your split by client and model, your contribution graph, and embeddable SVG cards for a README — ten templates, both themes, rendered server-side.

Small on your machine. The CLI is one job: scan, total, submit. It runs as a background service and otherwise stays out of the way.

Differences from Tokscale

This project is a fork of Tokscale. The data-collection core is shared and we keep pulling upstream's parser, pricing and correctness fixes. Everything above that has diverged:

	Tokscale	Tokens
CLI surface	Full TUI dashboard plus report commands (models, monthly, hourly, graph, wrapped, pricing, …)	Submit only — login, submit, serve, status. The TUI and every report command are removed, ~11k lines and 15 dependencies with them
Reporting	In the terminal	On the web, where it can be linked and compared
Anti-cheat	—	Cross-device duplicate guard, resubmit monotonicity checks, account bans, public Hall of Shame
Identity	Username	Verified badge from GitHub social links, refreshed daily
Groups	Team/group leaderboards	Removed — one global ranking
Frontend	Upstream's components	Rebuilt on shadcn/ui with its own brand marks and per-page Open Graph cards

Upstream sync policy: data capabilities and correctness fixes come in; UI implementations do not. The site keeps its own component set so the design stays consistent across updates.

Install

macOS

brew install owo-network/brew/tokens
tokens login
brew services start tokens        # keeps submitting in the background

Linux

curl -fsSL https://tokens.ci/install.sh | sh
tokens login

The installer sets up a systemd user service, so submission keeps running after you close the terminal.

Windows, or a one-off anywhere (Bun or Node 18+)

bunx tokens-cli@latest login      # or: npx tokens-cli@latest login
bunx tokens-cli@latest submit

Private mode

tokens login --private

Keeps your usage off the leaderboard and makes your profile, devices, badges and embeds answer as if the account did not exist. The command prints a read token (tkr_…) once; send it as Authorization: Bearer tkr_… or append ?token=tkr_… to a badge or embed URL to read your own data. Running it on a machine that is already logged in switches that account. Turn private mode off, and create or revoke read tokens, in Settings.

On every public profile, device names are shown masked (jo****ro).

Cloud agent sessions

Claude Code on the web runs in a cloud VM that tokens serve never sees. tokens cloud submit, run from the session's own end-of-turn hook, reports that usage with the same totals-only payload. Each session is its own device, keyed by a hash of the session id (never the id itself) and labelled by the server, so a resumed session is merged rather than counted twice, and a cloud device may only report its own agent's client. Codex cloud is not supported: its agent does not run in the container. Setup, the full rules and what was tested are in docs/cloud-sessions.md.

Who pays for this

Tokens is free to use and free to self-host, and the leaderboard reads each page from Postgres rather than from a cache of a cache. That is what keeps the numbers honest, and it is also the expensive way to do it. Neon cover that cost, so the board does not have to go behind a paywall or get thinner to fit a budget.

License

MIT — see LICENSE.

Built on Tokscale by Junho Yeo; credit for the original design and implementation goes to the upstream author and contributors.