TokenTracker

📊 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.

This project is tested with BrowserStack.

⚡ Quick Start

Requirements: Node.js 20+ (CLI runs on macOS / Linux / Windows; native desktop app ships for macOS (menu bar), Windows (system tray) and Linux (AppImage, tray). Cursor token reading uses the system sqlite3 CLI when available and falls back to node:sqlite on 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:

• 📊 A local dashboard at localhost:7680 with usage trends, model breakdown, cost analysis
• 🔌 Auto-detected hooks for every supported AI tool you have installed
• 🏠 Local-first — parses logs on your machine; no account or API keys required
• 🧩 Optional: a Skills tab that browses 250+ public skills and syncs them across Claude · Codex · Grok · Antigravity · Gemini · OpenCode · Hermes

Want 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.
• Linux — Download TokenTracker-linux-x86_64.AppImage → chmod +x and run. Tray app with the dashboard in a WebKitGTK window. It carries its own GTK/WebKit, so it needs nothing from your distro beyond a current glibc; on GNOME the tray icon still needs the AppIndicator extension. .deb and .rpm packages are also on the releases page — those link the distro's webkit2gtk-4.1, gtk3 and appindicator instead, so the .deb will not install on Debian 12 (use the AppImage there).

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

🍺 Homebrew (macOS)

Prefer brew? Install directly — no extra tap step needed:

# macOS menu bar app (DMG)
brew install --cask xiufengsun/tokentracker/tokentracker

# CLI only
brew install xiufengsun/tokentracker/tokentracker

Upgrade with brew upgrade --cask xiufengsun/tokentracker/tokentracker. The tap auto-bumps within an hour of every new release.

🐧 Linux (AppImage, .deb, .rpm)

Every release ships all three. One self-contained file, no package manager:

chmod +x TokenTracker-linux-x86_64.AppImage
./TokenTracker-linux-x86_64.AppImage

Or install through your package manager:

sudo apt install ./TokenTracker-linux-x86_64.deb    # Debian / Ubuntu
sudo dnf install ./TokenTracker-linux-x86_64.rpm    # Fedora / RHEL

Debian 12: the .deb depends on libappindicator3-1, which bookworm dropped in favour of libayatana-appindicator3-1, so apt refuses it. Use the AppImage.

All three bundle their own Node runtime and the dashboard. The AppImage additionally carries GTK3, WebKitGTK and appindicator, which is why it is ~120MB and installs nowhere; the .deb and .rpm link the distro's webkit2gtk-4.1, gtk3 and appindicator instead, at ~55MB. Tested on Arch + KDE Plasma; on GNOME the tray icon requires the AppIndicator extension, and clicking the tray icon opens the menu rather than the window (a libayatana-appindicator limitation).

An Arch PKGBUILD for a local pacman install lives in TokenTrackerLinux/packaging/arch/tokentracker-linux — see TokenTrackerLinux/README.md. It is not published to the AUR.

✨ Features

• 🔌 46 AI tools out of the box — Claude Code, Codex CLI, AStudio, Cursor, Gemini CLI, Antigravity, Kiro, OpenCode, OpenClaw, Every Code, Hermes Agent, GitHub Copilot, Kimi Code, CodeBuddy, WorkBuddy, WorkBuddy AI, Grok Build, oh-my-pi, OmO, pi, Dots, Prime Agent, Craft Agents, Reasonix, Muse Code, Kilo CLI, Kilo Code, Roo Code, Zed Agent, Goose, Droid, Mimo Code, DuMate, ZCode, Qoder, AnythingLLM Desktop, Claude Science, DeepSeek Harness, TRAE Work CN, LM Studio, Unsloth Studio, Devin CLI, Cline, MiniMax Code, Command Code, TRAE
• 🏠 Local-first — Runs on your machine. Parses logs locally with no account or API keys needed.
• 🚀 Zero config — Hooks auto-install on first run. From zero to dashboard in 30 seconds.
• 📊 Beautiful dashboard — Usage trends, cost breakdowns by model, GitHub-style activity heatmap, project attribution
• 🖥️ Native desktop app — macOS menu bar (+ widgets) and Windows system tray, each with an embedded server and the dashboard in a native webview
• 🐾 Desktop pet — A pixel companion powered by real coding activity: it works when you work, celebrates streaks, and sleeps when you rest
• 🎨 4 desktop widgets — Pin Usage / Activity Heatmap / Top Models / Usage Limits to your desktop
• 🏆 15 achievement tracks — Turn daily usage, streaks, tools, models, and milestones into collectible badges worth sharing
• 📈 Real-time usage limits — Claude / Codex / Cursor / Gemini / Kimi / Kiro / Grok / Copilot / Antigravity / ZCode / OpenCode Go / Qoder / Qoder CN / Command Code / Ark Coding Plan / Ark Agent Plan / Devin quota windows, with last-good caching when a local provider app is temporarily closed
• 🟢 Service Status page — live operational and incident status from 8 official provider status pages
• 💰 Cost engine — 2,200+ models priced via LiteLLM (auto-refreshed daily) + curated overrides for niche tools (Kiro, Cursor Composer, Kimi, CodeBuddy hy3); 24h disk cache + bundled offline snapshot mean accurate USD without an internet connection. Models without published vendor pricing (e.g. Tencent hy3-preview) are tracked by tokens but show $0 cost until the vendor publishes a rate.
• 🌐 Optional leaderboard — Compare with developers worldwide; drag-to-reorder columns to focus on the providers you care about (opt-in, sign in to participate)
• 🔄 Cross-device account view — Optional cloud sync merges usage across your machines (laptop, desktop, server) into one view. Off by default; local tracking stays independent.
• 🧩 Optional Skills tab — browse 250+ public skills from 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
• 🔒 Privacy-first — Local usage metrics only (token counts, timestamps, and model names). Prompts, completions, and code never leave your machine.

🖼️ Showcase

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 & skills.sh, install once, sync to Claude / Codex / AStudio / Grok / Antigravity / Gemini / OpenCode / Hermes. Per-target toggles, one-click Undo, no manual file copying.

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 .codex-pet.zip — V2 pets even turn their head to follow your cursor in 16 directions. macOS, Windows, and web.

Achievements — 15 tracks turn usage milestones, streaks, tools, and models into collectible badges — with progress visible before each unlock.

🔌 Supported AI Tools

Do I need to install any plugin or hook manually? No. tokentracker (or tokentracker init) handles everything on first run:

• Hook-based tools (Claude Code, Codex, AStudio, 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 set hooks.allowConversationAccess=true so OpenClaw permits the session-finished event that triggers sync. No download, no drag-and-drop.
• oh-my-pi — passive session scan is always the billing/token source of truth (~/.omp/agent/sessions/**/*.jsonl). When OMP is detected, tokentracker init also writes a managed notify extension to ~/.omp/agent/extensions/tokentracker-notify.ts so turns can trigger near-real-time sync. That file is owned only when it carries TokenTracker's managed marker: a same-named user-authored extension is never overwritten or deleted. tokentracker uninstall removes the extension only while it is still managed.
• OmO — passive session scan only (~/.omo/agent/sessions/**/*.jsonl, including nested subagent transcripts). No plugin or hook is installed. Path overrides, in precedence order: TOKENTRACKER_OMO_AGENT_DIR, then TOKENTRACKER_OMO_HOME / OMO_HOME (appended with /agent). PI_CONFIG_DIR and PI_CODING_AGENT_DIR are not honored: those belong to pi/omp.
• Cline — passive session scan only (~/.cline/data/sessions//*.messages.json, Cline CLI v3 / desktop app; the VS Code extension's globalStorage is a separate, older install and is not read). No hook is installed. Per-turn metrics are usage deltas where inputTokens already contains cache read+write, so only the non-cached remainder is billed. Path overrides, in precedence order: TOKENTRACKER_CLINE_SESSIONS_DIR, TOKENTRACKER_CLINE_DATA_DIR, TOKENTRACKER_CLINE_HOME, then Cline's own CLINE_SESSION_DATA_DIR, CLINE_DATA_DIR, CLINE_DIR.
• Passive readers (Cursor, Kiro, Hermes, Kimi Code, Copilot, Grok Build, OmO, pi, Craft Agents, Reasonix, Muse Code, Kilo CLI, Kilo Code, Roo Code, Antigravity, Zed Agent, Goose, Droid, Mimo Code, DuMate, ZCode, Qoder, LM Studio, Unsloth Studio, AnythingLLM Desktop, Devin CLI, MiniMax Code, Claude Science, DeepSeek Harness, Cline) — 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.db provides 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 a github-copilot-legacy aggregate rather than assigned to a guessed request model.
• Grok Build estimate — current local telemetry exposes cumulative updates.jsonl totalTokens, but not a stable prompt/output/cache split; signals.json remains a fallback with contextTokensUsed snapshots. TokenTracker estimates Grok cost until per-call usage details are available.
• Grok product shares — the Grok limits card keeps the shared weekly or monthly pool as the headline bar, then lists each product's share of that same pool (Grok Build, Cursor, Grok Bot, Imagine, and any later product the billing API reports). Those rows are shares of one cap, not separate quotas. Remaining mode flips the headline to percent left and leaves each product row as the used share.

Run tokentracker status anytime to verify every integration's state. If something shows skipped, the detail column explains why (e.g. tool CLI not on PATH, config unreadable).

Deeper dives: OpenClaw integration & troubleshooting.

Missing your tool? Open an issue — adding new providers is usually one parser file away.

🆚 Why TokenTracker?

Looking for a desktop app with widgets and a visual dashboard? TokenTracker pairs local log parsing across AI coding tools with native desktop apps, desktop widgets, provider quota tracking, and optional cloud sync.

🏗️ How It Works

flowchart LR
    A["AI coding tools<br/>Claude Code · Codex · AStudio · 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 · OmO · pi · Dots · Craft · Roo · Zed · Goose · Droid · Mimo · DuMate · ZCode · Qoder · AnythingLLM · Claude Science · DeepSeek Harness · TRAE · TRAE Work CN · LM Studio · Unsloth Studio · Devin CLI · Cline · MiniMax Code · Command Code"]
    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)]

1. AI CLI tools generate logs during normal use
2. Lightweight hooks detect changes and trigger sync (Cursor uses API instead of hooks)
3. Token counts parsed locally — prompts, responses, and code are never saved or uploaded
4. Aggregated into 30-minute UTC buckets
5. Dashboard, menu bar app, and widgets all read from the same local snapshot

Local features remain free and open source. Optional TokenTracker Cloud is the officially hosted cross-device analytics service; see the Cloud guide for plans, trial, and transition rules. Purchases are live at the same worldwide USD base price for recurring and fixed-term access: USD 4.99/month or USD 39.99/year before checkout tax (final amount shown by Waffo). Self-hosted software is free with infrastructure and maintenance handled by its owner; the complete installation is currently a technical preview.

🛡️ Privacy

📄 Full Privacy Policy — every network request the app can make, what each one sends, and how to switch it off.

TokenTracker processes your usage data locally. It never collects or uploads prompts, code, or model responses.

📦 Configuration

Most users never need this — defaults are sensible. For advanced setups:

🐧 Windows Subsystem for Linux (WSL) Auto-Discovery

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:

• Dual-Install Aggregation (both mode):
  • File-list & Active CLIs: Every Code, Kimi (legacy & Code), Gemini CLI, Antigravity, OpenCode (JSON), Codex CLI, AStudio, CodeBuddy, WorkBuddy, WorkBuddy AI, oh-my-pi (omp), pi, GitHub Copilot (OTEL), Roo Code, Craft, Kilo Code, Droid, Cline.
  • SQLite-based DBs: Hermes, Zed Agent, Goose, OpenCode (opencode.db), Kilo CLI, Mimo Code, DuMate, ZCode, Qoder, Claude Science (operon-cli.db), GitHub Copilot (App DB).
• WSL Auto-Discovery (Preference/Isolation only, no dual aggregation):
  • Grok Build (dynamically selects either native or WSL depending on the mode, but does not aggregate both in both mode).
  • Devin CLI (no native Windows data directory is known, so automatic discovery only ever finds a WSL install; native-only mode discovers nothing and both never aggregates a native copy). The TOKENTRACKER_DEVIN_DB override still points at an explicit database file.

Extra scan roots (multiple profiles, agent harnesses)

TokenTracker scans ~/.codex and ~/.claude (plus CODEX_HOME / CLAUDE_CONFIG_DIR when the syncing process has them set). If your sessions live somewhere else — a second profile, or an agent harness that gives Codex / Claude Code a private home — list those roots once in ~/.tokentracker/tracker/config.json and every sync (hook-triggered, app background refresh, CLI) walks them:

{
  "scanRoots": {
    "codex": ["~/.local/share/my-agent/codex"],
    "claude": ["~/.local/share/my-agent/claude", "~/.claude-work"]
  }
}

Each Codex root is expected to hold sessions/ (and optionally archived_sessions/), each Claude root a projects/ directory. Roots are de-duplicated by resolved path, so a profile whose projects/ is a symlink to another profile's is read once. tokentracker status and tokentracker doctor list the extra roots and flag any that are missing.

🛠️ Development

git clone https://github.com/xiufengsun/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

Building the macOS App

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.

🔧 Troubleshooting

ZCode totals decreased after v0.96.0? This release corrects historical cache/reasoning double counting, including previously uploaded months. See the ZCode history correction for the accounting change and local backup details.

CLI

"engines.node" or unsupported version error

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).

Port 7680 already in use

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).

A provider isn't being detected

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.

How to uninstall hooks and remove all config

tokentracker uninstall

This removes every hook TokenTracker installed across all detected AI tools, plus the local config and data. Safe to re-run.

macOS App

"TokenTrackerBar can't be opened" — unidentified developer

TokenTrackerBar is ad-hoc signed (not notarized with an Apple Developer ID — that requires a paid developer account). Gatekeeper blocks it on first launch.

1. Open System Settings → Privacy & Security
2. Scroll to the Security section — you'll see "TokenTrackerBar was blocked to protect your Mac."
3. Click Open Anyway
4. Confirm with Open in the follow-up dialog (you'll need to authenticate)

You only need to do this once. Older macOS alternative: right-click the app in Finder → Open → Open in the confirmation dialog.

"TokenTrackerBar is damaged and can't be opened"

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/TokenTracker.app

After that the app opens normally.

"TokenTrackerBar wants to access data from other apps"

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.

• ✅ Click Allow if you use Cursor or Kiro
• ❌ Click Don't Allow if you don't — those providers will be silently skipped, everything else keeps working

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.

🪪 README Badges

Show off your token usage on your GitHub profile or project README.

To get YOUR_USER_ID:

1. Run tokentracker, open the dashboard, and sign in to the leaderboard.
2. Go to Settings → Account.
3. Use the User ID shown there. On headless machines, tokentracker device-login also writes the same user_id to ~/.tokentracker/tracker/config.json.

Then drop one of these in:

[![tokens](https://srctyff5.us-east.insforge.app/functions/tokentracker-badge-svg?user_id=YOUR_USER_ID&metric=tokens)](https://github.com/xiufengsun/TokenTracker)
[![cost](https://srctyff5.us-east.insforge.app/functions/tokentracker-badge-svg?user_id=YOUR_USER_ID&metric=cost)](https://github.com/xiufengsun/TokenTracker)
[![rank](https://srctyff5.us-east.insforge.app/functions/tokentracker-badge-svg?user_id=YOUR_USER_ID&metric=rank)](https://github.com/xiufengsun/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.cc if you'd rather route clicks elsewhere.

Renders shields.io-compatible badges with your current totals (60s cache):

Privacy: badges only resolve for profiles where leaderboard sharing is on (Settings → Account → Public profile). Private profiles get a "private" placeholder.

⭐ Star History

🤝 Contributing & Support

• Bugs / feature requests: open an issue
• Security: see SECURITY.md — please don't open public issues for security reports
• Pull requests: see CONTRIBUTING.md for setup, tests, and how to add a new AI tool integration
• Questions / showcase: GitHub Discussions

🙏 Credits

The bot companion's morphing engine is bloub by Jérémy Perret (MIT).

The Clawd character design belongs to Anthropic. This is a community project with no official affiliation with Anthropic.

🔗 Friendly Links

• LINUX DO — a developer community we like

License

MIT

Token Tracker — Quantify your AI output.

tokentracker.cc · npm · GitHub

内容由编辑整理，部分信息来自 GitHub 与项目官网，版权归原作者所有。发现错误？报告问题