Javis603/token-monitor

Token Monitor – What it is

Token Monitor is a cross‑platform desktop widget that watches the token consumption and quota limits of dozens of AI‑powered coding assistants (Claude Code, GitHub Copilot, Cursor, etc.). It reads each tool’s local logs or API‑key balances, aggregates the data, and shows live numbers in a customizable dashboard. The app can sync those summaries across multiple machines so you always see a single, up‑to‑date view of your AI usage.

---

Core capabilities (as described in the README)

Capability	How it works	What you see
Live token tracking	Reads local transcript files, SQLite databases, or API‑key balance endpoints for 35+ supported tools.	Token count updates within seconds of each AI turn.
Per‑session breakdown	Opens a specific session (e.g., a Claude Code transcript) and parses the prompt/response token split.	Detailed view of input vs. output tokens, cache‑hit vs. miss, and which model was used.
Cost display	Uses built‑in price tables (or your manually entered subscription info) to convert tokens to USD, TWD, HKD, or CNY.	Tokens and monetary cost shown side‑by‑side; exchange rates refresh daily.
Quota/limit monitoring	Queries provider‑specific limits (daily, weekly, billing windows) from local exports or API‑key endpoints (OpenRouter, Minimax, etc.).	Visual quota bars, percentage‑full indicators, and alerts when a limit is near.
Historical trends & heatmaps	Stores daily aggregates locally (optionally archiving usage after source files are deleted).	Year‑long heatmap, streak counters, stacked bar/K‑line charts per tool or model.
Multi‑device sync	Sends a compact summary of the device’s usage to a hub (hosted in‑widget, self‑hosted Node, or Cloudflare Worker). Other devices receive updates via Server‑Sent Events.	All your machines show the same live numbers; iOS widgets can pull from the same hub.
Export	Writes token usage to CSV/JSON on demand or on a schedule.	Easy import into spreadsheets, Grafana, Obsidian, or custom scripts.
Custom UI	Menu‑bar (macOS) / system‑tray (Windows) pop‑over, floating bubble, macOS native widget preview, theme & opacity controls, drag‑and‑drop layout composer.	Choose the look that fits your workflow; add shortcuts, Discord Rich Presence, etc.

---

Supported tools (excerpt)

• Claude Code, Codex, OpenCode, Hermes Agent, OpenClaw, Cursor, Antigravity, Kimi, Qwen, Grok Build, GitHub Copilot, Pi, Zed, Kilo, Command Code, MiMo Code, ZCode, Kiro, CodeBuddy, WorkBuddy, Proma, Qoder CN, Reasonix, DeepSeek, Cherry Studio, LM Studio, Unsloth, OpenRouter, Minimax, Volcengine, Ollama, Trae CN, Alibaba Cloud, plus any third‑party API that follows the New API balance format.

---

Installation & first‑run

• macOS – brew install --cask token-monitor (Apple Silicon or Intel dmg).
  
• Windows – download the signed .exe (installer or portable).
  
• Linux – grab the AppImage (x64).
• Launch the app; it starts in local‑only mode, automatically detecting the supported tools on that machine and beginning to track usage.

---

Multi‑device synchronization options

1. Host hub in‑widget – pick one always‑on machine, copy the generated LAN URL + secret to other devices.
2. Self‑hosted Node hub – run npm run hub on a headless server after setting TOKEN_MONITOR_SECRET.
3. Cloudflare Worker hub – one‑click deploy button; paste the worker URL and secret into each client. All three use Server‑Sent Events, so updates appear on every connected widget within seconds.

---

Who might find this useful?

• Developers who use many AI coding assistants and need to keep track of token spend and quota exhaustion.
• Teams that share a budget for AI services and want a transparent, privacy‑first view of consumption.
• Freelancers or hobbyists who want to avoid surprise billing by seeing live cost alongside token counts.
• Anyone who works on multiple computers (desktop, laptop, WSL, iPhone) and wants a single dashboard rather than per‑machine monitors.

---

Privacy note

All prompt/response content stays on the local machine; only aggregated token counts, cost, and limit data are sent to the sync hub. The hub can be self‑hosted, run inside the widget, or deployed to Cloudflare, giving you full control over where the data travels.

---

Quick start checklist

1. Install the app for your OS.
2. Open Token Monitor – it will auto‑detect supported tools and start showing live usage.
3. (Optional) Set up a sync hub if you have more than one device.
4. Customize the dashboard layout, currency, and export settings to match your workflow.
5. Enjoy real‑time visibility of token spend and quota health across all your AI coding tools.