Why Token Watcher

Most token trackers recompute a report when you ask. Token Watcher watches
the logs as they're written: FSEvents → incremental parse → SSE push, the
dashboard updates in under a second while your agents work. Everything is
stored as per-request events, not pre-aggregated buckets — so you can
drill from a day, to a session, to a single request's token curve.

It also refuses to lie to you: estimated sources are labeled as such
(Antigravity ≈), models without pricing show up as unpriced instead of a
made-up cost, and vendor balances are reconciled against locally computed
spend so you can see when the estimate drifts.

Supported tools (13 sources)

Not supported: web chats (ChatGPT etc.) — token counts live server-side, nothing to parse.

Honest-caliber notes: Kimi Code, Qoder, Antigravity and Cursor were each
verified on real local data against an independent recomputation, row by row.
Qoder currently reports credits but zero tokens locally — credits go to a
dedicated ledger shown as a "credits spent" card, never fabricated into
tokens. Estimated sources are labeled (≈).

Quick start

npx --yes token-watcher@latest serve
# dashboard opens automatically → http://127.0.0.1:8787

Long-term:

npm install -g token-watcher
token-watcher serve
token-watcher install-agent             # launchd auto-start (macOS)
token-watcher bar                       # menu-bar capsule
token-watcher bar                       # macOS menu-bar capsule

Homebrew: brew install luwill/token-watcher/token-watcher

CLI reference

token-watcher today [--json|--light]            # today's usage (machine-readable / pure ASCII)
token-watcher sessions --day 2026-09-20 [--csv] [--git]   # per-session stats (+ git commit attribution)
token-watcher wrapped [--year 2026] [--json]    # year in review
token-watcher roi [--json]                     # subscription ROI (API-equivalent vs paid)
token-watcher leaderboard [on <name>|off|status|push|url <url>]
                                                # community leaderboard (opt-in, aggregate numbers only)
token-watcher doctor                            # environment + store + per-source health
token-watcher uninstall [--purge-data] [--yes]  # remove all local traces
token-watcher --version

Features

• Real-time: FSEvents on every source dir → incremental parse → SSE push (<1s)
• Incremental collection: byte cursors / sqlite watermarks / snapshot re-parse; dedup keys make rescans idempotent; collector versioning auto-backfills on logic upgrades
• Dashboard: metric cards, year-long GitHub-style heatmap (daily/weekly/cumulative), by-day/model/tool charts, live request feed
• Session drill-down: click any day → sessions (peak-context estimate) → per-request token curve
• Quotas: Codex official (direct-read), Claude official (local OAuth token → official usage endpoint; falls back to 5h window estimation)
• Subscription ROI: this month's API-equivalent cost vs what you actually pay (configure prices in ~/.tokenmeter/subscriptions.json; token-watcher roi)
• Balances & costs: DeepSeek/Kimi balance polling; LiteLLM pricing with per-model CNY conversion; balance reconciliation; Qoder credits ledger
• Community leaderboard (opt-in, off by default): see how your daily/weekly/30-day totals stack up against other users — aggregate numbers only, never your raw events. token-watcher leaderboard on <name>
• Health self-check: parse errors turn red, "file being written but no new events" turns yellow — silent format drift gets caught
• Exports & backups: CSV, session/annual CLI reports, daily VACUUM INTO snapshots (7 kept)

Subscription ROI

Edit ~/.tokenmeter/subscriptions.json with what you actually pay (one entry
per tool, price_cny or price_usd):

{ "monthly": {
    "claude-code": { "name": "Claude Max", "price_usd": 200 },
    "kimi":        { "name": "Kimi plan",  "price_cny": 49 },
    "glm":         { "tool": "zcode", "models": "glm", "name": "GLM Coding Plan", "price_cny": null },
    "minimax":     { "tool": "zcode", "models": "minimax", "name": "MiniMax (via ZCode)", "price_cny": null } } }

Entry keys are identifiers; tool selects the data source (needed when one
tool carries multiple subscriptions, e.g. GLM and MiniMax both flowing through
ZCode), and models filters aggregation by model prefix. Entries with the
price unset still show their API-equivalent, labeled "price not set".

The dashboard and token-watcher roi then compare this month's API-equivalent
cost (same pricing chain as the cost card, including peak/off-peak) against
your real spend. Clearly labeled as a hypothetical caliber: subscriptions come
with rate limits and API prices may be discounted. Credits-based tools (Qoder)
show this month's credits spent instead of a made-up ratio.

Community leaderboard (opt-in)

Off by default. Join explicitly with a nickname:

token-watcher leaderboard on <nickname>   # join (1-16 chars, no links/@)
token-watcher leaderboard status          # participation + last report state
token-watcher leaderboard push            # report once right now
token-watcher leaderboard off             # stop reporting; daily cleanup after 30d inactivity
token-watcher leaderboard url <https://…> # point at a self-hosted instance

What gets reported — aggregate numbers only, once per hour:

The panel can read the public leaderboard even before joining; only opted-in
clients upload usage aggregates. Viewing the panel makes a public GET request
without your random UUID when participation is disabled. doctor shows
the participation state either way. The reference backend is a
Cloudflare Worker + D1 (free tier) in cloud/ — anyone can
self-host one and point the CLI at it. Server-side defenses: name sanitizing,
all-field clamping, 16 KiB request limits, edge rate limiting, 60s per-ID throttling,
and daily cleanup of entries inactive for over 30 days (normally removed within 31 days).
The daily board uses UTC; the rolling-7-day and rolling-30-day boards require a report within 24 hours. Older clients without a 30-day total remain on the day/week boards until upgraded.

The dominant model follows the selected period: UTC today, rolling 7 days, or
rolling 30 days. It is the model with the largest total_tokens sum in that window;
its percentage is rounded against all tokens in the same window. Only the
winner is displayed; ties use model ID order. Events without a model remain in the
denominator but cannot be a dominant model. Model versions remain distinct.
Older reports containing only weekly models show a pending-update message on the
daily/30-day boards instead of reusing weekly data. Tool shares remain weekly.
ROI is a local-calendar-month hypothetical API-equivalent/monthly-fee ratio.
All figures are self-reported and unverified; this is not a competition or audited usage record.
The application database does not store IP addresses; Cloudflare processes network
metadata and uses source IPs for edge rate limiting.

Privacy

Fully local. The dashboard binds to 127.0.0.1 only (with Host validation).
API keys and tokens are used inside the server process only, never stored or
sent to the frontend. Usage data never leaves your machine — with one explicit
exception: the opt-in community leaderboard above, which sends only the
aggregate numbers listed there, only after you run leaderboard on.

Outbound requests (only these; none carry your usage data unless noted): FX
rate (12h), LiteLLM price table (24h), vendor balances (30min, with your key),
Claude official quota (10min, with Claude Code's local OAuth token), Cursor
usage CSV (30min, with a cookie built from local credentials), GLM Coding
Plan credit quota (10min, with ZCode's own local API key; MCP tool quota is
read from local logs only), leaderboard aggregate report (hourly, opt-in
only), and public leaderboard reads when viewing the dashboard.
Set TOKENMETER_OFFLINE=1 to skip all of them.

Requirements

Node ≥ 22.13 (node:sqlite). macOS fully supported (menu bar + launchd);
core pipeline CI-tested on macOS/Ubuntu/Windows. dsh source needs system
zstd. Non-official tool: parses private local formats that upstreams may
change — the health panel will flag it instead of failing silently.

Architecture

See docs/ARCHITECTURE.md (Chinese, with per-source
format notes and verification methodology). Core: one collector per source
under src/collectors/* (incremental + dedup + version), src/scanner.js
schedules, SQLite event store, HTTP API + SSE in src/server.js, zero-build
frontend in web/. Adding a source = one collector + registry entry + a
color. See CONTRIBUTING.md.

License

MIT