Local-first token usage analytics for coding agents.
Track token usage across Claude Code, Kimi Code, Codex, Cursor,
OpenCode, Grok CLI, Trae, and other supported tools.
墨 is the monochrome, newspaper-style theme.
Modern developers often use several coding agents at once. Each tool stores usage differently, so there is no single place to see where tokens went. whereToken discovers the data those agents already keep, normalizes it, and presents one view in the CLI, a local dashboard, and JSON.
It is designed to operate locally. Feedback and bug reports are welcome.
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/rainhuang0220/whereToken/main/scripts/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/rainhuang0220/whereToken/main/scripts/install.ps1 | iexCommand Prompt (without PowerShell):
curl.exe -fsSL -o "%TEMP%\wt-install.cmd" https://raw.githubusercontent.com/rainhuang0220/whereToken/main/scripts/install.cmd && call "%TEMP%\wt-install.cmd"Then, in the same terminal:
wheretokenHomebrew, go install, and source builds: Other install methods.
View token usage from every supported coding agent that has data on this machine.
See which application issued the request, which provider served the model, and which model was used.
Inspect daily totals, streaks, and cache hit rate.
Explore the same data in a browser interface that runs on your machine. A 2×5 KPI readout ends with the period's estimated cost — the per-vendor, per-model breakdown is one click away — and a deterministic usage portrait (用户画像: 高强度使用, 多模型探索, …) computed locally from your own numbers: bucketed traits and a fixed phrase bank, no ML, no network, and "no data" is never called "light usage".
Query usage from the terminal, or export a normalized JSON report for scripts.
whereToken reports token counts. When a public list price exists, it also shows an API-equivalent estimate. That is not a subscription bill, and a missing price is not written as $0. wheretoken pricing prints the full price card with each vendor's official source page and the date the rates were last verified; wheretoken pricing --usage prices your own ledger per model against the same card — per-category tokens and unit rates, with unpriced models shown as unavailable, never $0.
Publish a sanitized snapshot of local usage: GitHub-light/dark preview SVGs plus a static interactive page. The page is live in the browser. The numbers are a locally generated public snapshot, not a live cloud sync. wheretoken with no command is only the local report and does not upload that snapshot. The install scripts do not enable upload either. wheretoken profile refresh is one explicit PUT. wheretoken profile refresh on enables it and, on macOS, installs a user launchd agent; off disables the switch and uninstalls that agent. Linux and Windows do not install a background agent. Use wheretoken profile refresh watch for the foreground loop.
wheretoken profile build ./public-profile
wheretoken profile validate ./public-profile --production
wheretoken profile refreshBuild online. --offline is for tests and local-only fixtures; it skips Cursor/Trae account usage.
Point a GitHub Profile README at the previews and the live page (do not link the raw SVG as the destination). See docs/public-profile.md.
Synthetic demo. Your snapshot comes from your own machine.
wheretoken card path.svg still writes the 800×576 Vibe Coding Wall from the same snapshot. Prefer profile build for new READMEs.
Homebrew:
brew tap rainhuang0220/wheretoken
brew install wheretokenIf you already have Go:
go install github.com/rainhuang0220/whereToken/cmd/wheretoken@latestRelease binaries and brew tap include the dashboard. go install and brew --HEAD build the CLI only. To serve the dashboard from a clone, build the web UI (cd web && npm run build) and set WHERETOKEN_WEB to web/dist.
The npm/ wrapper is not on the npm registry yet. GitHub Release binaries are currently unsigned.
wheretoken
 |
 |
| By agent | By provider |
wheretoken --today
wheretoken --since 7d
wheretoken --json
wheretoken serve
wheretoken doctor
wheretoken pricing
wheretoken pricing --usage
wheretoken rebuild
wheretoken update
wheretoken uninstallwheretoken doctor explains which agents were found and whether their usage data is complete. wheretoken rebuild deletes the local scan cache and reads agent data again. Run wheretoken --help for the complete command reference.
Start the local dashboard with:
wheretoken serveThe dashboard runs locally on your machine. It provides a visual overview of token usage across supported coding agents, providers, and models. Use the refresh control in the page to rescan; reloading the browser tab does not.
窑 is whereToken's furnace mascot.
https://rainhuang0220.github.io/whereToken/ — landing page and a hands-on dashboard demo running on a synthetic sample ledger (no install, no backend).
The public site is a static GitHub Pages deployment: it reads nothing from your machine. The dashboard demo and /profile-demo/ use fabricated data; /profile/ may contain the maintainer's explicitly published, sanitized local snapshot. The local dashboard (wheretoken serve) is different: it binds 127.0.0.1, reads your real local ledgers, and never leaves your machine. Nothing scans a GitHub runner's HOME or uploads a ledger automatically. Deployment details: docs/deployment.md.
whereToken reads usage information from data made available by supported coding agents. Completeness varies by tool and may depend on whether the application is signed in.
| Coding agent | Usage data | Authentication |
|---|---|---|
| Claude Code | Full | Not required |
| Kimi Code | Full | Not required |
| Codex | Full | Not required |
| OpenCode | Full | Not required |
| Grok CLI | Full | Not required |
| MiniMax Agent | Full | Not required |
| OpenClaw | Full | Not required |
| Gemini CLI | Full | Not required |
| Qwen Code | Full | Not required |
| Cline | Full | Not required |
| Roo Code | Full | Not required |
Kilo Code (legacy VS Code + CLI kilo.db) |
Full | Not required |
| ZCode (Z.ai ADE) | Full | Not required |
| Cursor | Partial | Required for token columns |
| Trae / Trae CN / TRAE SOLO | Partial | Required |
Cursor and Trae must be signed in on this machine for token columns. Encrypted Trae storage is reported, not decrypted. Cline, Roo Code, and leftover Kilo Code VS Code tasks are read from ui_messages.json metrics only; settings and transcripts are skipped.
When a coding agent does not expose reliable usage information, whereToken reports the data as unavailable rather than treating it as zero. The dashboard labels each agent authoritative, degraded, estimated, or unavailable.
See docs/data-sources.md for how each agent is read and docs/token-accounting.md for the normalized token model.
Windsurf, GitHub Copilot, Continue, Aider, GLM/Doubao first-party CLIs, and Lingma are not currently supported because whereToken does not yet have a reliable safe usage ledger for these tools. Finding a config directory is not the same as finding usage. See docs/provider-matrix.md.
Coding agents
↓
Local files and, for some agents, their own usage APIs
↓
Source-specific adapters
↓
Normalized usage data
↓
CLI / Dashboard / JSON
whereToken discovers usage information from supported coding agents, normalizes source-specific records into a common representation, and exposes the result through the CLI, dashboard, and JSON output. Later scans reuse a local file index as a cache only; wheretoken rebuild deletes that index and reads the agents again.
It distinguishes the coding agent you use from the provider that served the model.
A request made through Claude Code using a MiniMax model is reported as:
- Agent: Claude Code
- Provider: MiniMax
whereToken is designed to operate locally and does not require a whereToken cloud service. Local-first remains the core.
Local analytics stay on this machine. Community Rank runs only when WHERETOKEN_COMMUNITY_URL is set; there is no public whereToken rank URL (a remote deploy blocker). When configured, it uploads anonymous daily totals only (participant UUID, local calendar day, token count, optional API-equivalent estimated cost, client version). A missing price is omitted, never sent as $0. It does not upload prompts, sessions, paths, request ids, credentials, raw events, or the SQLite index. Participation is on by default in that mode; wheretoken community off, WHERETOKEN_COMMUNITY=0, or DO_NOT_TRACK=1 turns it off. Rank 累计 is the sum of days this client uploaded, not the kiln 全部 ledger. This is not a global, worldwide, or all-AI-users rank. See docs/community.md.
Usage information is read from data made available by supported coding agents. Most sources are local application data.
Cursor and Trae may access those applications' own APIs using credentials already stored by the corresponding application, to obtain token columns that are not present in the local files.
whereToken does not ask users to paste API keys into the application. When an integration requires authentication, it uses local data or credentials already managed by that application.
For security issues and the project's security policy, see SECURITY.md. Do not include API keys, session tokens, or other secrets in bug reports.
whereToken is currently in alpha.
- Release binaries are currently unsigned (
docs/macos-signing.md) - An npm package is not currently published
- Some agents expose only partial usage information
- Some integrations require the corresponding application to be signed in
- The dashboard UI is currently Chinese-first
- CLI reference:
docs/wheretoken.1 - Data sources:
docs/data-sources.md - Token accounting:
docs/token-accounting.md - Cost estimate:
docs/cost.md - Community Rank:
docs/community.md - Public deployment:
docs/deployment.md - Adding an adapter:
docs/adding-an-adapter.md - JSON output format:
docs/cli-json.schema.json - Completions:
completions/ - Security policy:
SECURITY.md - Changelog:
CHANGELOG.md
For the complete CLI reference, environment variables, exit codes, and JSON output format, see the project documentation.
go test ./...
make test
make cicd web && npm install && npm test && npm run build
go run ./cmd/wheretoken serveMIT.