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.
Install
macOS / 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
Command 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:
wheretoken
Homebrew, go install, and source builds: Other install methods.
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. 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".
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; 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.
Public Profile
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 refresh
Build 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.
Compatibility: wheretoken card
wheretoken card path.svg still writes the 800×576 Vibe Coding Wall from the same snapshot. Prefer profile build for new READMEs.
Other install methods
Homebrew:
brew tap rainhuang0220/wheretoken
brew install wheretoken
If you already have Go:
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. GitHub Release binaries are currently unsigned.
Quick start
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 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. 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.
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
|
|
|
wheretoken-hosted
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). |
|
card
Package card builds a privacy-allowlisted public usage card and renders it as a deterministic static SVG.
|
Package card builds a privacy-allowlisted public usage card and renders it as a deterministic static SVG. |
|
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. |
|
proclock
Package proclock is a cross-process exclusive lock beside the config directory.
|
Package proclock is a cross-process exclusive lock beside the config directory. |
|
profile
Package profile turns a metric.Summary window into a deterministic, local user portrait for the dashboard.
|
Package profile turns a metric.Summary window into a deterministic, local user portrait for the dashboard. |
|
publicprofile
Package publicprofile builds a privacy-allowlisted public usage snapshot.
|
Package publicprofile builds a privacy-allowlisted public usage snapshot. |
|
scripts
|
|
|
gencarddemo
command
Command gencarddemo renders the committed Vibe Coding Wall demo SVG from the synthetic fixture in internal/card.
|
Command gencarddemo renders the committed Vibe Coding Wall demo SVG from the synthetic fixture in internal/card. |
|
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. |
|
gennewsprint
command
Command gennewsprint bakes the Newsprint substrate from a photoscanned paper material.
|
Command gennewsprint bakes the Newsprint substrate from a photoscanned paper material. |
|
genprofilecandidates
command
Command genprofilecandidates renders palette-review SVGs from an existing public snapshot.
|
Command genprofilecandidates renders palette-review SVGs from an existing public snapshot. |
|
genprofiledemo
command
Command genprofiledemo writes the committed synthetic public-profile bundle.
|
Command genprofiledemo writes the committed synthetic public-profile bundle. |
|
syncprofileassets
command
Command syncprofileassets rebuilds a committed profile bundle from its existing privacy-safe profile.json.
|
Command syncprofileassets rebuilds a committed profile bundle from its existing privacy-safe profile.json. |