xiufengsun/TokenTracker

Token Tracker

English · 简体中文 · 日本語 · 한국어 · Deutsch

Track every AI token — then bring your usage to life

An accurate, local-first token usage and cost dashboard for 43 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.

---

⚡ 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

• 🔌 43 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, Grok Build, oh-my-pi, OmO, pi, Dots, Prime Agent, Craft Agents, Reasonix, Kilo CLI, Kilo Code, Roo Code, Zed Agent, Goose, Droid, Mimo Code, 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

| Tool | Detection | Method | |---|---|---| | Claude Code | ✅ Auto | SessionEnd hook in settings.json | | Codex CLI | ✅ Auto | TOML notify hook in config.toml | | AStudio | ✅ 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) + managed notify extension written by tokentracker init to ~/.omp/agent/extensions/tokentracker-notify.ts for near-real-time sync (skipped if a same-named unmanaged file already exists; removed by tokentracker uninstall when still managed) | | 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) | | OmO | ✅ Auto | Passive reader (~/.omo/agent/sessions/**/*.jsonl, subagent transcripts included). Same session format as oh-my-pi but a separate install root, cursor namespace and source label, so both can be tracked side by side. Reasoning tokens are reported as a subset of output (Codex convention) and are never billed twice | | pi (@mariozechner/pi-coding-agent) | ✅ Auto | Passive reader (~/.pi/agent/sessions/**/*.jsonl) | | Dots | ✅ Auto | Routed through pi's provider split (pi-dots source, same passive reader) — no separate hook | | Prime Agent | ✅ Auto | Metadata-only passive usage reader (~/.prime/agent/sessions/*.jsonl; reads usage/model/provider/timestamp, never prompts or responses) | | Craft Agents | ✅ Auto | Passive session reader (~/.craft-agent + workspace session logs) | | Reasonix | ✅ Auto | Passive telemetry reader (~/.reasonix/**/*.jsonl.telemetry.json) | | 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) | | Qoder | ✅ Auto | Passive SQLite reader (Qoder/SharedClientCache/cache/db/local.db; reads assistant token_info, separates cached input, and never reads prompt or response text), plus Plan Credits and Ultimate Free Calls limits from Qoder's local session. Qoder CN (国内版, QoderCN/SharedClientCache/cache/db/local.db) is tracked as its own source with quota from qoder.com.cn. | | LM Studio | ✅ Auto | Passive recursive reader for ~/.lmstudio/server-logs//*.log; reads only final-response IDs, models, timestamps, and scalar usage counters from Chat Completions and Responses API records. Mirrored response IDs are deduplicated; prompt and response bodies are never retained. These developer-server records cover local inference and LM Link at zero marginal API cost, not Bionic Secure Cloud billing. | | Unsloth Studio | ✅ Auto | Passive SQLite reader for $UNSLOTH_STUDIO_HOME/studio.db (default ~/.unsloth/studio/studio.db). Reads scalar contextUsage metadata and content-free api_usage_events only; prompts, replies, attachments, API subjects, credentials, and training metrics are excluded. Local routes stay zero-cost, while known paid provider routes use the model that actually answered for estimated token cost. | | AnythingLLM Desktop | ✅ Auto | Passive SQLite reader (anythingllm-desktop/storage/anythingllm.db; reads per-message token metrics only, never prompts or responses) | | Devin CLI (Cognition) | ✅ Auto | Passive SQLite reader ($XDG_DATA_HOME/devin/cli/sessions.db, default ~/.local/share/devin/cli/sessions.db; reads per-request usage metrics deduplicated by request_id — replay/fork/compaction copies never double-count — using the recorded generation model, never prompts, responses, or cogs_json). Devin models (swe-2, swe-2-high, compactor) currently have no pricing data, so their token counts are reported but excluded from dollar estimates — a $0 figure does not mean free usage. No native Windows data dir is known; a WSL install is read via \\wsl$. | | Cline (CLI v3 / desktop app) | ✅ Auto | Passive reader (~/.cline/data/sessions//.messages.json). Per-turn metrics are usage deltas where inputTokens already includes cache read+write and outputTokens already includes reasoning, so the cached prefix is subtracted and reasoning is never billed twice; Cline's own per-call cost is trusted when reported. cline-free/ and cline-pass/* gateway models are priced at $0. The VS Code extension's globalStorage layout is not read. Path overrides: TOKENTRACKER_CLINE_SESSIONS_DIR, TOKENTRACKER_CLINE_DATA_DIR, TOKENTRACKER_CLINE_HOME, CLINE_SESSION_DATA_DIR, CLINE_DATA_DIR, or CLINE_DIR | | MiniMax Code | ✅ Auto | Passive reader (~/.minimax/v2/sessions/YYYY/MM/DD//messages.jsonl). Dedupes on message_id, records the routed upstream model per message, and ignores the always-zero usage.cost in favor of normal pricing. Override the directory with TOKENTRACKER_MINIMAX_HOME | | Command Code | ✅ Auto | Passive session reader (~/.commandcode/projects//.jsonl; *.checkpoints.jsonl snapshots and .prompts. sidecars are skipped). Scans transcripts locally and extracts selected usage metadata, including token counts and the CLI's costUsd display estimate. Token Tracker estimates cost with its shared model price table instead. Subtracts both cache reads and writes from cache-inclusive input to avoid double counting. Token Tracker does not persist or upload prompt, reply or code bodies. Override the directory with TOKENTRACKER_COMMANDCODE_HOME | | Claude Science | ✅ Auto | Passive SQLite reader (~/.claude-science/operon-cli.db; reads the frames table's token counters only, never prompts, artifacts or research content). No native Windows build — on Windows the app runs inside WSL and is read from there. | | DeepSeek Harness | ✅ Auto | Passive session reader (~/.dsh/sessions//session.jsonl[.zstd]; parses session header and assistant events, handles multi-frame zstd decompression) | | TRAE (international) | ✅ Auto | Local TRAE / TRAE SOLO SQLCipher usage metadata with the shared application key by default; optional TOKENTRACKER_TRAE_SQLCIPHER_KEY override. No vendor API calls. See setup and limitations. | | TRAE Work CN | ✅ Auto | Requires an explicit opt-in: set TOKENTRACKER_TRAE_CN_USAGE=1. Reading usage transmits the locally stored sign-in authorization to TRAE's internal API, so nothing is sent until you turn it on. Once opted in: during eligible non-background sync when local TRAE Work CN auth exists, reads session-token usage from the locally signed-in macOS / Windows app; its internal API may change |

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 belo