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
• 🏠 100% local — no account, no API keys, no network calls (except optional leaderboard)

Want a native macOS menu bar app? Download TokenTrackerBar.dmg → drag to Applications. Includes desktop widgets, menu bar status icon, and the same dashboard in a WKWebView.

Install globally for shorter commands:

npm i -g tokentracker-cli

tokentracker              # Open the dashboard
tokentracker sync         # Manual sync
tokentracker status       # Check hook status
tokentracker doctor       # Health check

🍺 Homebrew (macOS)

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

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

# CLI only
brew install mm7894215/tokentracker/tokentracker

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

✨ Features

• 🔌 8 AI tools out of the box — Claude Code, Codex CLI, Cursor, Gemini CLI, Kiro, OpenCode, OpenClaw, Every Code
• 🏠 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
• 🖥️ Native macOS app — Menu bar status icon, embedded server, WKWebView dashboard
• 🎨 4 desktop widgets — Pin Usage / Activity Heatmap / Top Models / Usage Limits to your desktop
• 📈 Real-time rate limit tracking — Claude / Codex / Cursor / Gemini / Kiro / Antigravity quota windows with reset countdowns
• 💰 Cost engine — 70+ model pricing tables, accurate USD breakdowns
• 🌐 Optional leaderboard — Compare with developers worldwide (opt-in, sign in to participate)
• 🔒 Privacy-first — Only token counts and timestamps. Never prompts, responses, or file contents.

🖼️ 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

🔌 Supported AI Tools

| Tool | Detection | Method | |---|---|---| | Claude Code | ✅ Auto | SessionEnd hook in settings.json | | Codex CLI | ✅ 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 |

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

🆚 Why TokenTracker?

| | TokenTracker | ccusage | Cursor stats | |--------------------------|:---:|:---:|:---:| | AI tools supported | 8 | 1 (Claude) | 1 (Cursor) | | Local-first, no account | ✅ | ✅ | ❌ | | Native menu bar app | ✅ | ❌ | ❌ | | Desktop widgets | ✅ 4 widgets | ❌ | ❌ | | Rate-limit tracking | ✅ 6 providers | ❌ | Cursor only |

🏗️ How It Works

flowchart LR
    A["AI CLI Tools<br/>Claude · Codex · Cursor<br/>Gemini · Kiro · OpenCode · ..."]
    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 — never any prompt or response content
4. Aggregated into 30-minute UTC buckets
5. Dashboard, menu bar app, and widgets all read from the same local snapshot

🛡️ Privacy

| Protection | Description | |---|---| | No content upload | Only token counts and timestamps. Never prompts, responses, or file contents. | | Local-only by default | All data stays on your machine. The leaderboard is fully opt-in. | | Auditable | Open source. Read src/lib/rollout.js — only numbers and timestamps. | | No telemetry | No analytics, no crash reporting, no phone-home. |

📦 Configuration

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

| Variable | Description | Default | |---|---|---| | TOKENTRACKER_DEBUG | Enable debug output (1 to enable) | — | | TOKENTRACKER_HTTP_TIMEOUT_MS | HTTP timeout in milliseconds | 20000 | | CODEX_HOME | Override Codex CLI directory | ~/.codex | | GEMINI_HOME | Override Gemini CLI directory | ~/.gemini |

🛠️ Development

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

CLI

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

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

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.

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