DEV Community

Kiell Tampubolon
Kiell Tampubolon

Posted on

Claude Token Monitor 🚀 — Real-Time Claude Usage HUD for Your Windows Desktop

#python #claude #productivity #opensource

Claude Token Monitor 🚀

⚠️ Disclaimer: This is an unofficial community-driven tool and is not affiliated, associated, endorsed by, or in any way officially connected with Anthropic, PBC.

Ever wonder how much of your Claude quota you've burned through mid-session? Claude Token Monitor is a local-first desktop utility that gives you a beautiful, always-on-top floating HUD showing your Claude usage in real time — covering both Claude.ai Web App quota and Claude Code CLI token consumption.

🔗 GitHub Repository: github.com/glatinone/claude-token-monitor-usage

📸 What It Looks Like

The HUD uses a sleek glassmorphism design with a circular progress ring that dynamically changes color:

  • 🟢 Green — Low usage
  • 🟡 Amber — Medium usage
  • 🔴 Red — High usage (time to slow down!)

You can drag it anywhere on your screen, collapse it into a tiny title pill with a double-click, and control it via the system tray.

✨ Key Features

  • Double-Sync Strategy:
    • Standalone Mode — Direct API polling using your saved sessionKey cookie
    • Browser Extension Sync — A companion Chrome Extension pushes live stats the moment you send a message on claude.ai
  • Always-on-Top Floating HUD — Circular progress ring, remaining quota %, and reset timer
  • Draggable & Position Memory — Drag it wherever you want; position is saved on exit
  • Claude Code CLI Integration — Real-time token parsing (Input, Output, Cache Write, Cache Read) with USD cost estimation based on Claude Sonnet pricing
  • Single-Instance Protection — TCP socket lock prevents duplicate processes or tray icon spam
  • 100% Private & Offline-First — All data lives in usage_data.json on your machine. The local server binds only to 127.0.0.1

🛠️ Architecture

Here's how the pieces fit together:

Web Browser (claude.ai)
  └── Chrome Extension MV3
        └── POST JSON ──────────────────────┐
                                            ▼
Terminal / IDE                     Desktop App (Python)
  └── Claude Code CLI               ├── Local HTTP Server :9988
        └── Writes logs ──►         ├── Log Watcher
              ~/.claude/projects/   ├── Direct API Fetcher
              *.jsonl               ├── Storage Manager
                                    ├── CTk Floating HUD
                                    └── Tray Manager
Enter fullscreen mode Exit fullscreen mode
  1. Log Watcher — Monitors %USERPROFILE%\.claude\projects\*.jsonl for CLI token events
  2. Local HTTP Server (port 9988) — Receives pushed JSON payloads from the Chrome Extension
  3. Direct Fetcher — Polls the Claude API directly using your sessionKey cookie when the extension isn't running

🚀 Installation & Setup

Prerequisites

  • Python 3.10+
  • Windows OS

1. Install the Desktop App 

git clone https://github.com/glatinone/claude-token-monitor-usage.git
cd claude-token-monitor-usage
pip install -r requirements.txt
python -m app.main
Enter fullscreen mode Exit fullscreen mode

Windows users can just double-click run.bat to install dependencies and launch in one step.

2. Standalone Mode (Session Key Setup)

To let the app query your quota directly without the extension:

  1. Open claude.ai and log in
  2. Press F12 → Application → Cookies → https://claude.ai
  3. Copy the value of the sessionKey cookie (starts with sk-ant-sid...)
  4. Right-click the C tray icon → Setup Session Key
  5. Paste and click OK — the widget syncs automatically!

3. Chrome Extension (Optional but Recommended)

  1. Open chrome://extensions
  2. Enable Developer Mode
  3. Click Load Unpacked → select the extension/ folder
  4. Open claude.ai and send a message — your quota syncs instantly!

🔒 Security & Privacy

  • Zero Cloud Sharing — Usage data stays strictly in app/usage_data.json on your local disk
  • Localhost Lock — The API server binds to 127.0.0.1 only; no LAN access
  • Credential Isolation — The Chrome Extension never touches your sessionKey. It's stored locally in app/config.json (git-ignored)

🤝 Contributing

Contributions are very welcome! Whether it's Linux/macOS support, UI improvements, or better CLI log parsing:

  1. Fork the repo
  2. Create your branch: git checkout -b feature/AmazingFeature
  3. Commit: git commit -m 'Add AmazingFeature'
  4. Push: git push origin feature/AmazingFeature
  5. Open a Pull Request

📄 License

MIT License — free to use, modify, and distribute.

🔗 Check out the full project on GitHub: github.com/glatinone/claude-token-monitor-usage

If you find it useful, drop a ⭐ on the repo and share it with fellow Claude power users!

Top comments (0)