tokentracker-cli
Advanced tools
Local-first AI coding token usage and cost tracker for 27 tools, with a dashboard, desktop pet, widgets, achievements, and native macOS/Windows apps.
English · 简体中文 · 日本語 · 한국어 · Deutsch
An accurate, local-first token usage and cost dashboard for 27 AI coding tools — plus a desktop pet, 4 native widgets, and 15 achievement tracks. No cloud account, no API keys, no setup.
📊 See the token dashboard in action
 |  |
| 🐾 A living desktop companion Codes, celebrates streaks, follows your cursor, and rests when you do. | 🧩 Four native widgets Usage, activity heatmap, top models, and rate limits at a glance. |
🏆 Unlock achievements from the way you actually code.
🎬 Meet TokenTracker
⭐ If TokenTracker saves you time, please star it on GitHub — it helps other developers find it.
Requirements: Node.js 20+ (CLI runs on macOS / Linux / Windows; native desktop app ships for both macOS (menu bar) and Windows (system tray). Cursor token reading uses the system
sqlite3CLI when available and falls back tonode:sqliteon supported Node releases).
npx tokentracker-cli
That's it. First run installs hooks, syncs your data, and opens the dashboard at http://localhost:7680.
What you get in 30 seconds:
localhost:7680 with usage trends, model breakdown, cost analysisWant a native desktop app?
- macOS — Download
TokenTrackerBar.dmg→ drag to Applications. Menu bar status icon, desktop widgets, and the dashboard in a WKWebView.- Windows — Download
TokenTracker-Setup.exe→ run the per-user installer (no admin needed). System-tray app with the dashboard in WebView2. Portable zip also on the releases page.
Install globally for shorter commands:
npm i -g tokentracker-cli
tokentracker # Open the dashboard
tokentracker sync # Manual sync
tokentracker status # Check hook status
tokentracker status --json # Machine-readable summary (pipe to jq, ingest from AI agents)
tokentracker status --light # Plain ASCII table (CI / SSH, no spinner)
tokentracker doctor # Health check
Prefer brew? Install directly — no extra tap step needed:
# macOS menu bar app (DMG)
brew install --cask mm7894215/tokentracker/tokentracker
# CLI only
brew install mm7894215/tokentracker/tokentracker
Upgrade with brew upgrade --cask mm7894215/tokentracker/tokentracker. The tap auto-bumps within an hour of every new release.
anthropics/skills, ComposioHQ/awesome-claude-skills, skills.sh and any GitHub repo you add; sync them across Claude / Codex / Grok / Antigravity / Gemini / OpenCode / Hermes with named targets and one-click Undo|
Dashboard — usage trends, model breakdown, cost analysis 
|
Desktop Widgets — pin usage to your desktop 
|
|
Menu Bar App — animated Clawd companion + native panels 
|
Global Leaderboard — compare with developers worldwide 
|
|
Skills Manager — browse 250+ public skills from GitHub & 
| |
|
Desktop Pet — a pixel companion that floats on your desktop and reacts to your real token burn: it codes when you code, celebrates streaks, and sleeps when you rest. Import community pets from codex-pets.net with a link or a 
| |
|
Achievements — 15 tracks turn usage milestones, streaks, tools, and models into collectible badges — with progress visible before each unlock. 
|
| Tool | Detection | Method |
|---|---|---|
| Claude Code | ✅ Auto | SessionEnd hook in settings.json |
| Codex CLI | ✅ Auto | TOML notify hook in config.toml |
| Cursor | ✅ Auto | API + SQLite auth token |
| Kiro | ✅ Auto | SQLite + JSONL hybrid |
| Gemini CLI | ✅ Auto | SessionEnd hook |
| OpenCode | ✅ Auto | Plugin system + SQLite |
| OpenClaw | ✅ Auto | Session plugin |
| Every Code | ✅ Auto | TOML notify hook |
| Hermes Agent | ✅ Auto | SQLite sessions table (~/.hermes/state.db) |
| GitHub Copilot App / CLI | ✅ Auto | Unified per-request SQLite usage (~/.copilot/session-store.db); App DB legacy baseline |
| GitHub Copilot Chat extension / legacy CLI | ✅ Auto | OpenTelemetry file exporter (COPILOT_OTEL_FILE_EXPORTER_PATH) |
| Kimi Code | ✅ Auto | Passive wire.jsonl reader (~/.kimi/sessions/**/wire.jsonl) |
| oh-my-pi (Pi Coding Agent) | ✅ Auto | Passive reader (~/.omp/agent/sessions/**/*.jsonl) |
| CodeBuddy (Tencent) | ✅ Auto | SessionEnd hook in ~/.codebuddy/settings.json (Claude-Code fork) |
| WorkBuddy (Tencent) | ✅ Auto | SessionEnd hook in ~/.workbuddy/settings.json (Claude-Code fork) + passive projects/**/*.jsonl scan |
| Grok Build (xAI) | ✅ Auto | SessionEnd hook + passive updates.jsonl / signals.json scan (~/.grok/sessions/**/) |
| Kilo CLI (kilo.ai) | ✅ Auto | Passive SQLite reader (~/.local/share/kilo/kilo.db, OpenCode-fork schema) |
| Kilo Code (VS Code extension) | ✅ Auto | Passive ui_messages.json reader (Cursor/Code/CodeBuddy/Windsurf globalStorage) |
| Antigravity | ✅ Auto | Passive transcript reader (~/.gemini/{antigravity,antigravity-ide,antigravity-cli}/brain/**/transcript.jsonl) |
pi (@mariozechner/pi-coding-agent) | ✅ Auto | Passive reader (~/.pi/agent/sessions/**/*.jsonl) |
| Craft Agents | ✅ Auto | Passive session reader (~/.craft-agent + workspace session logs) |
| Roo Code (VS Code extension) | ✅ Auto | Passive ui_messages.json reader (rooveterinaryinc.roo-cline) |
| Zed Agent | ✅ Auto | Passive SQLite reader (threads.db, all providers — hosted zed.dev + bring-your-own) |
| Goose (Block) | ✅ Auto | Passive SQLite reader (sessions.db, cumulative deltas) |
| Droid (Factory) | ✅ Auto | Passive session reader (~/.factory/sessions/**/settings.json, cumulative deltas) |
| Mimo Code (mimocode) | ✅ Auto | Passive SQLite reader (~/.local/share/mimocode/mimocode.db, OpenCode-fork schema; counts only mimo-native turns — mirrored Claude/claude-mem history is excluded) |
| ZCode (Z.ai) | ✅ Auto | Passive SQLite reader (~/.zcode/cli/db/db.sqlite, OpenCode-fork schema; counts only Z.ai/BigModel GLM turns — bundled Claude/Codex/Gemini sub-agents are excluded) |
| AnythingLLM Desktop | ✅ Auto | Passive SQLite reader (anythingllm-desktop/storage/anythingllm.db; reads per-message token metrics only, never prompts or responses) |
Do I need to install any plugin or hook manually? No.
tokentracker(ortokentracker init) handles everything on first run:
- Hook-based tools (Claude Code, Codex, Gemini, Every Code, CodeBuddy, WorkBuddy, Grok Build) — we write a SessionEnd hook or TOML notify entry into the tool's own config.
- Plugin-based tools (OpenCode, OpenClaw) — plugins ship inside the npm package. OpenClaw's session plugin lives at
~/.tokentracker/tracker/openclaw-plugin/openclaw-session-sync/; we link and enable it via OpenClaw's own CLI, then sethooks.allowConversationAccess=trueso OpenClaw permits the session-finished event that triggers sync. No download, no drag-and-drop.- Passive readers (Cursor, Kiro, Hermes, Kimi Code, Copilot, Grok Build, oh-my-pi, pi, Craft Agents, Kilo CLI, Kilo Code, Roo Code, Antigravity, Zed Agent, Goose, Droid, Mimo Code, ZCode, AnythingLLM Desktop) — nothing is installed into those tools. We only read files they already produce (SQLite DB, JSONL, OTEL export, session logs). Copilot App / CLI usage is read per request from
~/.copilot/session-store.db;data.dbprovides the one-time legacy adoption baseline and stays observe-only after the store becomes canonical, while the Chat extension and legacy CLI continue using OTEL. TokenTracker coordinates the sources so overlapping requests are counted once. Mixed App/CLI usage that predates adoption is retained as agithub-copilot-legacyaggregate rather than assigned to a guessed request model.- Grok Build estimate — current local telemetry exposes cumulative
updates.jsonltotalTokens, but not a stable prompt/output/cache split;signals.jsonremains a fallback withcontextTokensUsedsnapshots. TokenTracker estimates Grok cost until per-call usage details are available.Run
tokentracker statusanytime to verify every integration's state. If something showsskipped, thedetailcolumn explains why (e.g. tool CLI not onPATH, config unreadable).Deeper dives: OpenClaw integration & troubleshooting.
Missing your tool? Open an issue — adding new providers is usually one parser file away.
Looking for a ccusage alternative with a GUI? TokenTracker covers 27 tools (not just Claude Code), adds native macOS and Windows apps + desktop widgets, and de-duplicates token records correctly across providers — so your numbers match the providers' own billing.
| TokenTracker | ccusage | Cursor stats | |
|---|---|---|---|
| AI tools supported | 27 | 1 (Claude) | 1 (Cursor) |
| Local-first, no account | ✅ | ✅ | ❌ |
| Native desktop app | ✅ macOS + Windows | ❌ | ❌ |
| Desktop widgets | ✅ 4 widgets | ❌ | ❌ |
| Rate-limit tracking | ✅ 7 providers | ❌ | Cursor only |
| Accurate multi-provider dedup | ✅ | ❌ ¹ | — |
¹ reqId-based deduplication over-counts providers that omit a request ID (DeepSeek / Kimi / MiniMax / Claude sub-agents) by 1.6–3.7×. TokenTracker dedups on a composite key, so totals match each provider's own billing dashboard.
flowchart LR
A["AI coding tools<br/>Claude Code · Codex · Cursor · Gemini · Kiro<br/>OpenCode · OpenClaw · Every Code · Hermes · Copilot<br/>Kimi Code · CodeBuddy · WorkBuddy · Grok Build · Kilo CLI · Kilo Code<br/>Antigravity · oh-my-pi · pi · Craft · Roo · Zed · Goose · Droid · Mimo · ZCode · AnythingLLM"]
A -->|hooks trigger| B[Token Tracker]
B -->|parse logs<br/>30-min UTC buckets| C[(Local SQLite)]
C --> D[Web Dashboard]
C --> E[Menu Bar App]
C --> F[Desktop Widgets]
C -.->|opt-in| G[(Cloud Leaderboard)]
| Protection | Description |
|---|---|
| No content upload | Only token counts and timestamps. Never prompts, responses, or file contents. |
| Local-only by default | All data stays on your machine. The leaderboard is fully opt-in. |
| Auditable | Open source. Read src/lib/rollout.js — only numbers and timestamps. |
| Anonymous usage stats only | Two things phone home, both anonymous: (1) at most one daily heartbeat — a one-way hash of the machine id, app version, OS platform, and app shell (cli/mac/win); (2) anonymous dashboard pageview/feature events (PostHog — autocapture and session recording disabled, browser Do-Not-Track respected). Never token counts, model names, prompts, or paths. Audit src/lib/telemetry.js and dashboard/src/lib/analytics.js; one switch disables both on your machine: TOKENTRACKER_NO_TELEMETRY=1 (or DO_NOT_TRACK=1). |
Most users never need this — defaults are sensible. For advanced setups:
| Variable | Description | Default |
|---|---|---|
TOKENTRACKER_DEBUG | Enable debug output (1 to enable) | — |
TOKENTRACKER_NO_TELEMETRY | Disable all anonymous telemetry — daily heartbeat and dashboard analytics (1 to disable; the DO_NOT_TRACK standard is also respected) | — |
TOKENTRACKER_HTTP_TIMEOUT_MS | HTTP timeout in milliseconds | 20000 |
TOKENTRACKER_WSL_MODE | WSL install resolution behavior on Windows (for aggregating native and WSL installations). wsl-first (prefer WSL), native-first, wsl-only, native-only, both (aggregate both installs) | wsl-first |
CODEX_HOME | Override Codex CLI directory | ~/.codex |
GEMINI_HOME | Override Gemini CLI directory | ~/.gemini |
TOKENTRACKER_GROK_HOME | Override Grok Build directory for the Grok integration and Skills Manager | ~/.grok |
GROK_HOME | Legacy Grok Build directory override, used when TOKENTRACKER_GROK_HOME is unset | ~/.grok |
TOKENTRACKER_ANTIGRAVITY_HOME | Force a single Antigravity Skills directory (auto-detects ~/.gemini/antigravity + ~/.gemini/antigravity-ide otherwise) | auto |
If you run AI coding agents inside WSL on Windows, TokenTracker can auto-discover and aggregate metrics from both native Windows and WSL installations.
Configure this behavior using the TOKENTRACKER_WSL_MODE environment variable:
both (Recommended): Scans and aggregates metrics from both native Windows and WSL.wsl-first (Default): Checks WSL first; if found, uses WSL metrics, otherwise falls back to Windows.native-first: Checks native Windows first; if found, uses Windows metrics, otherwise falls back to WSL.wsl-only: Scans WSL environment only.native-only: Scans native Windows environment only.[!NOTE] Preference (
-first) vs. Isolation (-only): Preference modes prioritize your choice but gracefully fall back to scanning the other environment if the tool is missing. Isolation modes strictly lock scanning to that single environment and ignore the other completely.
Supported providers for WSL auto-discovery and aggregation:
both mode):
opencode.db), Kilo CLI, Mimo Code, ZCode, GitHub Copilot (App DB).both mode).git clone https://github.com/mm7894215/TokenTracker.git
cd TokenTracker
npm install
# Build dashboard + run CLI
cd dashboard && npm install && npm run build && cd ..
node bin/tracker.js
# Tests
npm test
cd TokenTrackerBar
npm run dashboard:build # Build the dashboard bundle
./scripts/bundle-node.sh # Bundle Node.js + tokentracker source
xcodegen generate # Generate the Xcode project
ruby scripts/patch-pbxproj-icon.rb # Patch in the Icon Composer asset
xcodebuild -scheme TokenTrackerBar -configuration Release clean build
./scripts/create-dmg.sh # Package the .app into a DMG
Requires Xcode 16+ and XcodeGen.
TokenTracker requires Node 20+. Check your version:
node --version
If lower, upgrade via nvm, fnm, or your package manager (brew upgrade node, apt install nodejs).
The dashboard server picks the next free port automatically (7681, 7682, ...) when 7680 is taken. The actual port is logged on startup. If you want to force a specific port:
PORT=7700 tokentracker serve
To find what's holding 7680:
lsof -i :7680
WSL2 note: on Windows hosts the Delivery Optimization service (DoSvc) listens on 7680, and under NAT networking the conflict is invisible from inside WSL — the server starts fine but the Windows browser reaches DoSvc instead. TokenTracker therefore defaults to 7681 when running under WSL (logged on startup).
Check the integration status:
tokentracker status
Then run the doctor for a deeper health check:
tokentracker doctor
If a provider shows as not configured even though you use it, try tokentracker activate-if-needed to re-run hook detection. If still missing, open an issue with the doctor output attached.
tokentracker uninstall
This removes every hook TokenTracker installed across all detected AI tools, plus the local config and data. Safe to re-run.
TokenTrackerBar is ad-hoc signed (not notarized with an Apple Developer ID — that requires a paid developer account). Gatekeeper blocks it on first launch.
You only need to do this once. Older macOS alternative: right-click the app in Finder → Open → Open in the confirmation dialog.
This is Gatekeeper reacting to the com.apple.quarantine attribute macOS attaches to every downloaded file — not an actual problem. Clear it once with:
xattr -cr /Applications/TokenTrackerBar.app
After that the app opens normally.
This is required for the Cursor and Kiro integrations. They store auth tokens / usage data inside their own ~/Library/Application Support/ folders, which macOS protects with the App Management permission.
Once granted, the permission is remembered. Note that ad-hoc signed builds re-prompt after each upgrade because each build has a new signing identity.
Show off your token usage on your GitHub profile or project README.
To get YOUR_USER_ID:
tokentracker, open the dashboard, and sign in to the leaderboard.tokentracker device-login also writes the same user_id to ~/.tokentracker/tracker/config.json.Then drop one of these in:
[](https://github.com/mm7894215/TokenTracker)
[](https://github.com/mm7894215/TokenTracker)
[](https://github.com/mm7894215/TokenTracker)
The link target defaults to the TokenTracker repo so every click helps other developers discover the tool. Swap it for your leaderboard profile, personal site, or
https://www.tokentracker.ccif you'd rather route clicks elsewhere.
Renders shields.io-compatible badges with your current totals (60s cache):
| Param | Values | Default |
|---|---|---|
metric | tokens / cost / rank | tokens |
period | week / month / total | total |
style | flat / flat-square | flat |
label | any short string | metric name |
color | hex, e.g. ff6b35 | brand green |
Privacy: badges only resolve for profiles where leaderboard sharing is on (
Settings → Account → Public profile). Private profiles get a "private" placeholder.
The Clawd character design belongs to Anthropic. This is a community project with no official affiliation with Anthropic.
Token Tracker — Quantify your AI output.
tokentracker.cc · npm · GitHub
FAQs
Local-first AI coding token usage and cost tracker for 27 tools, with a dashboard, desktop pet, widgets, achievements, and native macOS/Windows apps.
The npm package tokentracker-cli receives a total of 3,805 weekly downloads. As such, tokentracker-cli popularity was classified as popular.
We found that tokentracker-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
A fake corepack.org site is impersonating the Node.js tool and delivers an infostealer and proxyware to developers who download it.
Research
/Security News
A large-scale campaign abused GitHub Actions in compromised repositories to exploit CVE-2026-41940 in cPanel and WHM and steal server credentials.
Security News
Five frontier LLMs generated the same nonexistent package names, leaving 53 available for potential slopsquatting across PyPI and npm.