README
¶
whereToken
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.
Features
Unified usage overview
View token usage from every supported coding agent that has data on this machine.
Agent, provider, and model breakdown
See which application issued the request, which provider served the model, and which model was used.
Historical usage
Inspect daily totals, streaks, and cache hit rate.
Local dashboard
Explore the same data in a browser interface that runs on your machine. The KPI row ends with the period's estimated cost and a short, explainable usage profile (高强度使用, 多模型探索, …) computed locally from your own numbers — no ML, no network, and "no data" is never called "light usage".
CLI and JSON
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.
Installation
Recommended: Homebrew
brew tap rainhuang0220/wheretoken
brew install wheretoken
Prebuilt binaries
macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/rainhuang0220/whereToken/main/scripts/install.sh | bash
Windows (PowerShell):
irm https://raw.githubusercontent.com/rainhuang0220/whereToken/main/scripts/install.ps1 | iex
Windows (Command Prompt, the C:\Users\…> window):
curl.exe -fsSL -o %TEMP%\wt-install.cmd https://raw.githubusercontent.com/rainhuang0220/whereToken/main/scripts/install.cmd && %TEMP%\wt-install.cmd
The script prints the installed path (~/.local/bin/wheretoken on Unix, %LOCALAPPDATA%\whereToken\bin\wheretoken.exe on Windows). Run that line. Open a new terminal if the command is not on PATH yet.
Build from source
go install github.com/rainhuang0220/whereToken/cmd/wheretoken@latest
Release 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.
Quick start
wheretoken
| By agent | By provider |
wheretoken --today
wheretoken --since 7d
wheretoken --json
wheretoken serve
wheretoken doctor
wheretoken pricing
wheretoken rebuild
wheretoken update
wheretoken uninstall
wheretoken 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.
Dashboard
Start the local dashboard with:
wheretoken serve
The 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.
Live Demo
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 and shows fabricated demo data only. The local dashboard (wheretoken serve) is a different thing: it binds 127.0.0.1, reads your real local ledgers, and never leaves your machine. Deployment details: docs/deployment.md.
Supported coding agents
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.
Not currently supported
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.
How it works
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
Privacy & Security
Local-first
whereToken is designed to operate locally and does not require a whereToken cloud service. Local-first remains the core.
Data collection
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.
Data sources
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.
Credentials
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.
Security policy
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.
Limitations
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
Documentation
- 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.
Development
go test ./...
make test
make ci
cd web && npm install && npm test && npm run build
go run ./cmd/wheretoken serve
License
MIT.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
wheretoken
command
|
|
|
internal
|
|
|
adapter/cline
Package cline reads Cline task metrics from ui_messages.json.
|
Package cline reads Cline task metrics from ui_messages.json. |
|
adapter/gemini
Package gemini reads Gemini CLI session recordings.
|
Package gemini reads Gemini CLI session recordings. |
|
adapter/kilo
Package kilo reads Kilo Code usage from leftover VS Code task metrics and from the Kilo CLI 1.x OpenCode-shaped kilo.db.
|
Package kilo reads Kilo Code usage from leftover VS Code task metrics and from the Kilo CLI 1.x OpenCode-shaped kilo.db. |
|
adapter/qwen
Package qwen reads Qwen Code's dedicated token-usage JSONL.
|
Package qwen reads Qwen Code's dedicated token-usage JSONL. |
|
adapter/roo
Package roo reads Roo Code task metrics from ui_messages.json.
|
Package roo reads Roo Code task metrics from ui_messages.json. |
|
adapter/vsctask
Package vsctask reads VS Code-family task metrics JSON used by Cline and Roo Code (ui_messages.json say=api_req_started and siblings).
|
Package vsctask reads VS Code-family task metrics JSON used by Cline and Roo Code (ui_messages.json say=api_req_started and siblings). |
|
adapter/zcode
Package zcode reads ZCode (Z.ai's agentic IDE) request-level usage from the v2 SQLite store at ~/.zcode/cli/db/db.sqlite (model_usage rows).
|
Package zcode reads ZCode (Z.ai's agentic IDE) request-level usage from the v2 SQLite store at ~/.zcode/cli/db/db.sqlite (model_usage rows). |
|
community
Package community is the anonymous aggregate Community Rank layer.
|
Package community is the anonymous aggregate Community Rank layer. |
|
index
Package index is a local performance cache for parsed usage events.
|
Package index is a local performance cache for parsed usage events. |
|
insight
Package insight builds deterministic, re-derivable usage lines from a Summary.
|
Package insight builds deterministic, re-derivable usage lines from a Summary. |
|
price
Package price estimates API-equivalent USD cost from normalized usage.
|
Package price estimates API-equivalent USD cost from normalized usage. |
|
scripts
|
|
|
gendemo
command
Command gendemo fabricates a synthetic multi-source ledger and writes the static JSON payloads the public demo site serves.
|
Command gendemo fabricates a synthetic multi-source ledger and writes the static JSON payloads the public demo site serves. |