claude-dongle

Your Claude Code usage limits, live — without breaking your flow.

A floating pill that shows how much of your usage windows you've burned (5-hour session and weekly, per model) and predicts when you'll hit the wall. It reads everything from Claude Code's own local token: no proxy, no extra login, nothing sent anywhere.

Unofficial. This project is not affiliated with Anthropic. It reads the same undocumented usage endpoint that powers Claude Code's own limit warnings (api.anthropic.com/api/oauth/usage) — if Anthropic changes it, the monitor may stop showing data until updated.

✨ Features

• Always-on dongle — a discreet pill in the corner with your session (5h), week, and week-per-model usage. It appears only when it makes sense (e.g. with your editor or terminal open) and hides when you're not working.
• Overflow forecast — computes your burn rate by regression over recent usage and estimates the ETA to 100%. The border breathes amber when, at the current pace, you'll run out before the reset, and red when a limit that stops every model is spent. A single model running out (say your weekly Fable) leaves the border alone: the others keep working.
• Pace marker — every ring has a tick for where you'd be at a linear pace. Fill ahead of the tick = burning fast; behind it = comfortable. You read your pace at a glance, no math.
• Per-model usage — from Claude Code's local logs, it shows which models ate your week (with a 14-day heatmap). Not per project: attributing by the session's working directory is wrong often enough to mislead, and doing it right is a different tool's job.
• What's still usable — a model running out of its weekly quota doesn't stop the others, so the panel says exactly that, and when it comes back.
• Budget, not just a threat — the forecast answers "can I take one more task?": ~2h30 of work left · the reset only comes in 1d 23h.
• Your burn by hour of the day — built from the history it already keeps, it shows the hours you actually spend the window on.
• Easy on the battery — every timer runs at half rate while unplugged.
• Limit notifications — alerts when you cross a threshold, when a limit is reached and on the overflow forecast, each limit tracked as its own series. Everything crossing in the same reading arrives as one notification, a minimum gap paces the routine ones, and you can snooze them all for a while. Works even with the dongle closed, via a background timer.
• English or Portuguese — a switch in the settings changes the whole panel and the notifications on the spot; by default it follows your system locale.
• Cross-platform — Linux, macOS and Windows, with native autostart on each.

🖼️ Preview

The usage gauges, live

Dashboard	Forecast, per-model usage and settings, expanded

Limit and overflow-forecast alerts — they fire even with the dongle closed

See CHANGELOG.md for what changed in each release.

📦 Installation

Requirements: Python 3.9+ and Claude Code installed and logged in on the machine.

With pipx (recommended — installs into an isolated env):

pipx install claude-dongle

Or with pip:

pip install --user claude-dongle

pipx install git+https://github.com/PedroHenrique0713/claude-dongle

Then:

claude-dongle tray      # open the dongle
claude-dongle setup     # (optional) launch it automatically on login

setup wires up autostart the native way on each OS — systemd user on Linux, LaunchAgent on macOS, Startup folder on Windows. Undo it with claude-dongle uninstall.

⚙️ Usage

Dongle interactions: drag to reposition (it snaps to edges); click to open the dashboard; middle-click to refresh now. The border breathes amber when the current pace overflows before the reset, and red when a limit that stops every model is spent — one model running out leaves it alone.

🔧 Configuration

Tune it from the panel or by editing ~/.config/claude-dongle/config.json:

🔍 How it works

Claude Code keeps an OAuth token in ~/.claude/.credentials.json (on macOS, in the Keychain). claude-dongle uses that token to query Anthropic's usage endpoint (api.anthropic.com/api/oauth/usage) — the same one that powers Claude Code's own limit warnings. From there:

• monitor assembles the state; with no real source (API down and no cache) it shows -- instead of inventing a number.
• history keeps a local time series (SQLite) for the burn rate and forecast.
• projects aggregates tokens per model by reading the JSONL files in ~/.claude/projects — deliberately not per project: attributing by the session's working directory is wrong often enough to mislead.
• dongle and dashboard (PyQt6, hand-drawn) render everything; notifier raises the alerts.

🔒 Privacy

Everything is local. The monitor reads Claude Code's token and talks directly to Anthropic's official API — no data is sent to any third party, and the token never leaves the machine nor gets rewritten (the monitor keeps what it needs in its own cache, with owner-only file permissions, without touching Claude Code's file).

🛠️ Development

Run from the repo without installing:

./run.sh tray                 # Linux/macOS
python -m claude_dongle tray  # any OS

Run the tests:

pip install pytest
pytest tests/

Regenerate the README assets (rendered by the app itself, offscreen, with fictional data):

python scripts/gen_screenshots.py   # dongle, dashboard, notifications
python scripts/gen_gif.py           # the animated usage rings

📄 License

MIT © Pedro Henrique — see LICENSE.