Javis603/token-monitor

Local-first desktop widget for tracking token usage, costs, and limits across 35+ AI coding tools—including Claude Code, Codex, Cursor, OpenCode, and OpenClaw—with multi-device sync.

1,957

stars

635

commits

JavaScript

primary language

Sep 6, 2026

updated

javis-ai.com/token-monitor/

ai-tools

antigravity

claude-code

codex

cursor

deepseek

deepseek-harness

dsh

hermes-agent

linux

llm

local-first

macos

openclaw

opencode

self-hosted

token-tracker

token-usage

windows

README

EN | 简 | 繁 | KO | JA

Token Monitor

One live dashboard for every AI coding tool, synced across every machine.

What is Token Monitor?

A desktop widget that shows live token usage and AI Tool Limits across 32+ AI coding tools — Claude Code, Codex, Cursor, GitHub Copilot, Cherry Studio, and more — with real-time multi-device sync, historical usage trends, and breakdowns by tool, device, model, session, or project.

Supported Tools

Token Monitor supports token usage, account-limit checks, and session details separately:

Tool	Data path	Token Usage	AI Tool Limits	Session Details
Claude Code	`~/.claude/projects/`, `~/.claude/transcripts/`	✅	✅	✅
Codex	`~/.codex/` (`sessions/`, `archived_sessions/`)	✅	✅	✅
OpenCode	`~/.local/share/opencode/` (`opencode*.db`, `storage/message/`)	✅	✅	✅
Hermes Agent	`~/.hermes/state.db`	✅	—	—
OpenClaw	`~/.openclaw/agents/`	✅	—	—
Cursor IDE / Cursor CLI	`~/.config/tokscale/cursor-cache/` (account-level usage export)	✅	✅	—
Antigravity	`~/.gemini/` (`antigravity/`, `antigravity-ide/`, `antigravity-backup/`, `antigravity-cli/conversations/`)	✅	✅	—
Cline	VS Code globalStorage tasks (`.../saoudrizwan.claude-dev/tasks/`), `~/.cline/data/sessions/`	✅	—	—
Kimi CLI / Kimi Code / Kimi Work	`~/.kimi/sessions/`, `~/.kimi-code/sessions/`, `<platform-app-data>/kimi-desktop/`	✅	✅	—
Qwen CLI	`~/.qwen/projects/`	✅	—	—
Grok Build	`~/.grok/` (`sessions/`, `logs/unified.jsonl`)	✅	✅	—
GitHub Copilot	VS Code `workspaceStorage/*/chatSessions/`, `~/.copilot/` (`otel/`, `data.db`)	✅	✅	—
Pi / Oh My Pi	`~/.pi/agent/sessions/`, `~/.omp/agent/sessions/`	✅	—	—
Zed	`~/.local/share/zed/threads/threads.db`	✅	—	—
Kilo Code	VS Code globalStorage tasks (`.../kilocode.kilo-code/tasks/`) — Linux & remote/WSL only	✅	—	—
Command Code	`~/.commandcode/projects/*/.jsonl`	✅	✅	—
MiMo Code	`~/.local/share/mimocode/mimocode.db`	✅	✅	—
ZCode / GLM	`~/.zcode/` (`projects/`, `cli/db/db.sqlite`)	✅	✅	—
Kiro	`~/.kiro/sessions/cli/`, Kiro IDE globalStorage & `kiro-cli` DB	✅	✅	—
CodeBuddy	`~/.codebuddy/projects/` + IDE / VS Code extension logs	✅	—	—
WorkBuddy	`~/.workbuddy/projects/`, `~/.workbuddy/workbuddy.db`	✅	✅	—
Proma	`~/.proma/agent-sessions/*.jsonl`	✅	—	—
Qoder	`<platform-app-data>/QoderCN/SharedClientCache/cache/db/local.db` (CN only)	✅	✅	—
Reasonix	`~/.reasonix/` (`stats/`, `sessions/`, `projects/*/sessions/`)	✅	—	—
DeepSeek / DeepSeek Harness	`~/.dsh/sessions/` (`session.jsonl`, `session.jsonl.zstd`)	✅	✅	✅
Cherry Studio	`<platform-app-data>/CherryStudio/` (`Data/Agents/.claude/projects/` V2, `.claude/projects/` legacy)	✅	—	—
OpenRouter	OpenRouter API key (usage/key limit; balance when credits access is authorized, documented for Management keys)	—	✅	—
Minimax	Minimax API key (Token Plan quota via Minimax API)	—	✅	—
Volcengine	Ark API key or Volcengine AK/SK (Ark Coding Plan quota via Volcengine API)	—	✅	—
Ollama	Ollama Cloud cookie (session/weekly usage via ollama.com/settings)	—	✅	—
Trae CN	Trae CN access token (Trae CN / SOLO credits via trae.cn)	—	✅	—
Third-party APIs	New API / Sub2API-compatible account presets (including compatible One API forks), a New API API-key preset, and a Custom balance endpoint	—	✅	—

Notes, Custom balance endpoints, and data paths overridden by environment variables

Paths above are the defaults. Token Monitor follows the same environment overrides Tokscale does — $XDG_DATA_HOME for the ~/.local/share/ roots, and per-tool variables such as $CODEX_HOME, $GROK_HOME, $HERMES_HOME, $KIMI_CODE_HOME, $DSH_HOME, $REASONIX_STATE_HOME, $REASONIX_HOME and the $CLINE_* family.
Command Code transcripts do not contain actual token counts or per-message model metadata. Token usage is estimated from transcript text, while model attribution and derived cost may reflect the currently configured model rather than the model historically used for each request.
The Cursor cache comes from Cursor's account-level usage export, so it covers Cursor IDE and Cursor CLI alike. Token Monitor automatically detects accounts signed in through the Cursor desktop app and also supports adding accounts manually in Settings. The cache re-syncs automatically when stale, but newly finished sessions can take a few minutes to reach Cursor's dashboard, so usage updates on sync rather than instantly.
Custom maps numeric JSON fields from one GET balance endpoint; OpenAI or Anthropic compatibility alone is not enough.

Qoder CN (local adapter)

Qoder CN token usage is read from the app's local SQLite database, not an API — enable it in Settings → tools (opt-in, off by default). The database is auto-detected per platform: macOS ~/Library/Application Support/QoderCN/SharedClientCache/cache/db/local.db, Windows %APPDATA%\QoderCN\SharedClientCache\cache\db\local.db, Linux ~/.config/QoderCN/SharedClientCache/cache/db/local.db — overridable with TOKEN_MONITOR_QODER_CN_DB_PATH.

This is an advanced local integration: reading needs a sqlite3 CLI on PATH or a Node runtime with unflagged node:sqlite (Node ≥ 23.4; the Electron widget may need the CLI). Read failures are logged, and an existing complete snapshot is retained instead of being replaced with zero usage. Costs are estimated from the models.dev catalog for each mapped model; the adapter may break if Qoder changes its database schema.

Showcase

_{Customizable dashboard — choose which modules show and their order}	_{Multiple accounts side by side, one-click switch of the active Codex account}	_{Click any tool to expand input / output and cache-hit detail}
_{Open a single session to break each prompt into tokens and tools used}	_{Every model's usage and cost, aggregated across tools}	_{Each device's usage, cost, and sync status — expand for per-machine detail}

_{A year of activity heatmap and streaks, aggregated across all devices}

_{A year of daily trends, stacked by tool / model, with K-line}

Why Token Monitor?

Most usage monitors are useful on the machine they run on. Token Monitor is built for multi-device work: each device watches its own local logs, sends summary updates to your hub, and every connected widget sees token changes almost immediately.

Features

Tracking usage

Live token tracking — Claude Code, Codex, Cursor, GitHub Copilot, Antigravity, OpenCode, and 26+ AI tools, with the UI updating within seconds of each turn (full list in the table above)
Per-session detail — open a Claude Code, Codex, or OpenCode session to see tokens per prompt, expandable to each reply's exact token split and tools used (read on-demand from local transcripts or databases, never synced)
Cache hit statistics — click any tool or model to expand a detailed breakdown of input tokens (cache hit vs miss), output tokens, and hit-rate percentages
Cost & currency — cost alongside token counts, shown in USD, TWD, HKD, or CNY; exchange rates auto-update daily and can be manually overridden in Settings
WSL usage (Windows) — file-based usage from a running WSL distro is detected automatically and merged about every 5 minutes; SQLite-backed tools such as OpenCode and Hermes may require a headless agent inside WSL

Limits, trends & export

AI Tool Limits detection — provider-specific session, weekly, billing, and credits windows for Claude Code, Codex, Cursor, OpenRouter, third-party APIs, GLM, Kimi, and 21+ providers, including multiple OpenRouter/third-party profiles and DeepSeek prepaid balance/spend
Multiple accounts & Codex switching — track several accounts per provider, each with its own limits; a tracked Codex account can be switched as the active local account in one click, without re-authenticating
Preserve deleted session usage — many tools prune old sessions (Claude Code drops transcripts after 30 days by default), losing that history. When enabled, Token Monitor archives observed daily tool/model usage locally so the heatmap and trends survive even after the source files are gone (see Session data retention below)
Usage Trends & Dashboard — a home-screen activity heatmap and trend chart, plus a dedicated dashboard window with streaks and stacked per-tool/per-model history (bar and K-line views) across all your devices
Optional Status view — Claude, OpenAI, Cursor, and DeepSeek status pages, with manual or interval re-checks
Data export — export usage as tool-agnostic CSV + JSON, manually or auto-written to a folder, for spreadsheets, Obsidian, Grafana, or scripts; see docs/export.md
Subscription records — record by hand what each AI account actually costs; the plan label's tooltip then reports the price, the next renewal or end date, time subscribed, and the month's usage cost as a multiple of what the plan costs, for recurring plans and top-up ledgers alike

Multi-device & deployment

Real-time multi-device sync — Server-Sent Events push an update on one device to the others within seconds
Local-first — no servers needed for single-device use
Self-hosted sync backend — in-widget hub, Node CLI hub, or Cloudflare Worker
iOS widget support — Widgy and Scriptable through the Worker hub
Privacy-first — prompts, responses, source code, and file contents stay on your machine

Interface & surfaces

Breakdown views — grouped by tool, device, model, session, project, or account limits
Menu bar (macOS) and system tray (Windows) popover — live cost, tokens, or the closest-to-empty provider limit % next to the icon
Floating Bubble mode — collapses the widget into a draggable mini-window with click or hover preview and tray-style content
Menu bar layout composer — the menu bar and the floating bubble can use a built-in preset or a layout you build yourself: pick "Custom…" to add AI tool icons, quota bars, percentages, reset times, cost, or custom text, drag to reorder against a live preview, and give each item its own AI tool, account, quota window, and typeface
Appearance controls — interface theme switching (incl. a light mode), per-tool vendor colours, glass opacity, blur, and transparent window mode
Experimental native macOS Widget — macOS 14+ support in Small, Medium, and Large sizes, with Overview, Quota, Models, Activity, and Trend pages. This source-only preview is not yet promised in published releases.
Customizable tool list — hide, pin, and reorder tools in the main dashboard without changing what gets tracked
Recordable global shortcut — show or hide the window from anywhere
Discord Rich Presence — broadcast today's tokens, cost, and top client (opt-in)

Installation

Download from GitHub Releases.

macOS (Apple Silicon) — .dmg, signed and notarized
macOS (Intel) — x64 .dmg, signed and notarized
Windows 10/11 — setup and portable .exe, code-signed
Linux x64 — .AppImage

Packaged builds check GitHub Releases automatically. When an update is available, the app shows an update indicator; supported platforms can also install from Settings → General.

First run

Local mode is the default: launch the app and it starts tracking this device. No hub, agent, or config required.

Multi-device sync

Pick ONE hub backend that all your devices (and any headless agents) connect to. On each device, open the widget and pick a mode under Settings → Multi-device Sync. The widget contributes this device's usage automatically; run npm run agent only on machines without a widget.

In the widget on one always-on machine, open Settings → Multi-device Sync and pick Host hub on this device. The widget generates a random secret and lists the LAN URLs other devices can connect to (Tailscale or ZeroTier addresses appear here too). On every other device, pick Connect to a hub and paste the URL + secret.

The hub runs while Token Monitor is running — quitting (not just closing the window) stops it for all connected devices.

Option B — Self-hosted Node hub (always-on headless machine)

# on the always-on machine
cp .env.example .env
# set TOKEN_MONITOR_SECRET to something private, then:
npm run hub

Option C — Cloudflare Worker hub (across networks, including iPhone)

One-click deploy — Cloudflare will prompt for the TOKEN_MONITOR_SECRET during setup. Or deploy manually:

cd worker
npm install
npx wrangler login
npx wrangler secret put TOKEN_MONITOR_SECRET
npx wrangler deploy

Paste the deployed URL into each device's widget at Settings → Multi-device Sync. See worker/README.md for the iOS widget recipe and endpoint reference, or docs/API.md for the hub HTTP API.

App data

App state lives in the OS user-data dir — delete it along with the app to fully uninstall.

Platform	Path
macOS	`~/Library/Application Support/Token Monitor/`
Windows	`%APPDATA%/Token Monitor/`
Linux	`~/.config/Token Monitor/`

Build from source

To build your own installer, use Node.js 22.15+ on the target OS (electron-builder can't cross-build a macOS .dmg on Windows, or vice-versa).

npm install
npm run dist:mac     # macOS arm64 .dmg           → dist/
npm run dist:mac:x64 # macOS Intel x64 .dmg       → dist/
npm run dist:win     # Windows x64 installer .exe → dist/
npm run dist:linux   # Linux x64 AppImage         → dist/
npm run pack         # unpacked app dir (no installer), for quick local testing

Output lands in dist/. Windows and Linux use the matching dist:* script above on the target OS. Packaging the macOS release build requires a local Developer ID Application signing identity; use npm start for local development or unsupported platforms.

Runtime and packaging scripts explicitly ensure the pinned tokscale binary on the four vendored targets. Other source platforms keep the npm binary and filter clients it does not support; npm install, lint, and tests do not download it.

How it works

Mode A — Local (default, no setup)
    widget (Electron) ──▶ tokscale ──▶ ~/.claude, ~/.codex, $HERMES_HOME

Mode B — Sync (opt-in, multi-device)
    device A agent ──▶
    device B agent ──▶  hub  ──▶  widget on any device
    device C agent ──▶

The widget chooses local vs sync mode based on Settings → Multi-device Sync. The hub itself can run as a separate npm run hub process, a Cloudflare Worker, or directly inside one of the widgets (Host mode). In sync mode the hub pushes aggregated stats to every connected widget over Server-Sent Events, so updates on one device appear on the others within a few seconds.

Session data retention

With Preserve deleted session usage enabled (Settings → Collection), Token Monitor archives observed daily tool/model usage locally with no time limit — so even after a source tool prunes its own sessions, the heatmap and trends are unaffected.

Advanced: extend the source tool's own retention

The heatmap and sync payload use a rolling 370-day window (older observations remain available locally for future views). Claude Code keeps only 30 days of transcripts by default (cleanupPeriodDays); to keep the full rolling year before the archive kicks in, raise it in ~/.claude/settings.json before the window passes:

{
  "cleanupPeriodDays": 370
}

A larger value keeps more, at the cost of transcripts living on disk for as long as you set. tokscale's Session Data Retention table covers the other tools' defaults and config paths.

This archive only covers days Token Monitor has already observed; data deleted before it started tracking cannot be recovered.

Settings

There are two places to configure Token Monitor; day-to-day use only needs the first:

Widget (GUI) — click the ⚙ button in the bottom-right corner. Sections, in order: General (language, launch at login, updates), Main (Home modules and display currency), Window (window behavior, menu bar and floating-bubble layout, tray mode, shortcut), Appearance (theme and vendor colours), Collection (tracked tools, collection cadence, Preserve deleted session usage, data export), AI Tool Limits (provider selection, limits, and credentials), Subscriptions (what you pay per account), and Multi-device Sync. The ⇧ button in the title bar cycles the window behavior.
Headless agent & hub — no UI; configured with a .env file at the project root (copy from .env.example), precedence CLI flag → env var → built-in default.

See the configuration reference for every setting and all environment variables.

Privacy

Token Monitor processes usage logs locally and sends no analytics or telemetry to the project maintainer. Network access occurs only for documented or user-enabled features. See the privacy policy for the data used by updates, provider integrations, Discord Rich Presence, and optional multi-device sync.

Star History

Contributing

Issues and PRs are welcome. Project conventions, architecture notes, and the command reference live in AGENTS.md — written for coding agents, but it doubles as the contributor guide.

Acknowledgments

tokscale for log parsing and token accounting.
CodexBar for AI Tool Limits research.
Code signing policy: Free code signing provided by SignPath.io, certificate by SignPath Foundation.

License

MIT © @Javis

Contributors

(top 30 of 32)

570 commits

10 commits

4 commits

4 commits

See what people are saying

X (2)

Local token tracker for 32+ AI coding tools. token-monitor tracks usage and cost across assistants: - Covers Claude Code, Codex, Cursor, OpenCode, and more - Desktop widget with multi-device sync Stop guessing your AI coding spend. https://t.co/DaxLd7D5Hi

@so_sthbryan · 2 likes · Aug 31, 2026

Similar repos

junhoyeo/tokscale

🛰️ Track token usage across AI coding agents from your terminal. 🏅 Global leaderboard with…

5,384

Javis603/token-monitor

README

Token Monitor

What is Token Monitor?

Supported Tools

Qoder CN (local adapter)

Showcase

Why Token Monitor?

Features

Tracking usage

Limits, trends & export

Multi-device & deployment

Interface & surfaces

Installation

First run

Multi-device sync

Option A — Host the hub from the widget (easiest, no CLI)

Option B — Self-hosted Node hub (always-on headless machine)

Option C — Cloudflare Worker hub (across networks, including iPhone)

App data

Build from source

How it works

Session data retention

Settings

Privacy

Star History

Contributing

Acknowledgments

License

Contributors

See what people are saying

Similar repos

Languages

Javis603/token-monitor

README

Token Monitor

What is Token Monitor?

Supported Tools

Qoder CN (local adapter)

Showcase

Why Token Monitor?

Features

Tracking usage

Limits, trends & export

Multi-device & deployment

Interface & surfaces

Installation

First run

Multi-device sync

Option A — Host the hub from the widget (easiest, no CLI)

Option B — Self-hosted Node hub (always-on headless machine)

Option C — Cloudflare Worker hub (across networks, including iPhone)

App data

Build from source

How it works

Session data retention

Settings

Privacy

Star History

Contributing

Acknowledgments

License

See what people are saying

Similar repos

Contributors

Languages