@ipv9/tokentracker-cli

Token Tracker

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

Know exactly what you're spending on AI — across every CLI

Auto-collect token counts from 22 AI coding tools, aggregate them locally, and see real cost trends in a beautiful dashboard. No cloud account, no API keys, no setup — just one command.

If TokenTracker saves you time, please star it on GitHub — it helps other developers find it.

Quick Start

Requirements: Node.js 20+. Cursor token reading uses the system sqlite3 CLI when available and falls back to node:sqlite on supported Node releases.

npx --yes @ipv9/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, 24h/day/week/month views, and visible-only auto-refresh
• Auto-detected hooks for every supported AI tool you have installed
• 100% local — no account, no API keys, no network calls (except optional leaderboard)
• Optional: a Skills tab that browses 250+ public skills and syncs them across Claude · Codex · Grok · Antigravity · Gemini · OpenCode · Hermes

Install globally for shorter commands:

npm install -g @ipv9/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

Features

• 22 AI tools out of the box — Claude Code, Codex CLI, Cursor, Gemini CLI, Antigravity, Kiro, OpenCode, OpenClaw, Every Code, Hermes Agent, GitHub Copilot, Kimi Code, CodeBuddy, Grok Build, oh-my-pi, pi, Craft Agents, Kilo CLI, Kilo Code, Roo Code, Zed Agent, Goose
• 100% local — Token data never leaves your machine. No account, no API keys.
• 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, 24h detail view, browser-timezone "Updated" timestamp, and configurable visible-only auto-refresh (Off, 30s, 60s, 120s; default 30s)
• Real-time rate limit tracking — Claude / Codex / Cursor / Gemini / Kiro / Copilot / Antigravity quota windows with reset countdowns
• 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)
• 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 — Only token counts and timestamps. Never prompts, responses, or file contents.

Showcase

Dashboard — usage trends, model breakdown, cost analysis	Global Leaderboard — compare with developers worldwide
Skills Manager — browse 250+ public skills from GitHub & skills.sh, install once, sync to Claude / Codex / Grok / Antigravity / Gemini / OpenCode / Hermes. Per-target toggles, one-click Undo, no manual file copying.

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, Gemini, Every Code, CodeBuddy, Grok Build) — we write a SessionEnd hook or TOML notify entry into the tool's own config.
• Plugin-based tools (OpenCode, OpenClaw) — the plugin ships inside the npm package (~/.tokentracker/app/openclaw-plugin/). We link it via the tool's own CLI (openclaw plugins install --link … + enable). 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) — nothing is installed into those tools. We only read files they already produce (SQLite DB, JSONL, OTEL export, session logs).
• 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.

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 ccusage alternative with a GUI? TokenTracker covers 22 tools (not just Claude Code), adds a local dashboard, and de-duplicates token records correctly across providers — so your numbers match the providers' own billing.

_{¹ 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.}

How It Works

flowchart LR
    A["AI CLI Tools<br/>Claude · Codex · Cursor · Gemini · Kiro<br/>OpenCode · OpenClaw · Every Code · Hermes · Copilot · Kimi Code · CodeBuddy · Grok Build · oh-my-pi · pi · Craft · Roo Code · Zed · Goose"]
    A -->|hooks trigger| B[Token Tracker]
    B -->|parse logs<br/>30-min UTC buckets| C[(Local SQLite)]
    C --> D[Web Dashboard]
    C -.->|opt-in| E[(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 — never any prompt or response content
4. Aggregated into 30-minute UTC buckets
5. Dashboard reads from the local snapshot, displays timestamps in your browser timezone, and auto-refreshes visible tabs every 30 seconds by default
6. In local mode, dashboard auto-refresh also starts a background local sync and refreshes again only when new 30-minute buckets were queued

Privacy

Configuration

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

Dashboard refresh behavior

The local dashboard is designed to stay current without hammering the local sync path:

• Auto-refresh runs only while the dashboard tab is visible.
• The default interval is 30s; the selector supports Off, 30s, 60s, and 120s.
• If an older browser session has a removed 10s preference saved, TokenTracker falls back to 30s.
• Manual refresh runs local sync first in local mode, then reloads dashboard data.
• Auto-refresh starts local sync in the background, keeps the UI responsive, and only performs a second data reload when sync reports new 30-minute buckets.
• The Total tokens panel shows an Updated ... timestamp formatted in the browser's timezone, so you can tell when the displayed snapshot last refreshed.

Development

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

Troubleshooting

CLI

node --version

PORT=7700 tokentracker serve

lsof -i :7680

cd: /Users/you/src/TokenTracker: No such file or directory

bash scripts/install-local-service.sh

launchctl print gui/$(id -u)/com.pitimon.tokentracker.local-sync
tail -n 50 ~/.tokentracker/tracker/logs/local-sync.err.log

tokentracker status

tokentracker doctor

tokentracker uninstall

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/pitimon/TokenTracker)
[![cost](https://srctyff5.us-east.insforge.app/functions/tokentracker-badge-svg?user_id=YOUR_USER_ID&metric=cost)](https://github.com/pitimon/TokenTracker)
[![rank](https://srctyff5.us-east.insforge.app/functions/tokentracker-badge-svg?user_id=YOUR_USER_ID&metric=rank)](https://github.com/pitimon/TokenTracker)

The link target defaults to the TokenTracker repo so every click helps other developers discover the tool. Swap it for your leaderboard profile or personal site 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 Clawd character design belongs to Anthropic. This is a community project with no official affiliation with Anthropic.

License

MIT