Metadata-Version: 2.4
Name: claude-dongle
Version: 1.1.0
Summary: Claude Code rate-limit monitor: floating dongle + dashboard (burn rate, overflow forecast, per-project usage).
License: MIT License
        
        Copyright (c) 2026 Pedro Henrique
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/PedroHenrique0713/claude-dongle
Project-URL: Repository, https://github.com/PedroHenrique0713/claude-dongle
Project-URL: Issues, https://github.com/PedroHenrique0713/claude-dongle/issues
Keywords: claude,claude-code,usage,rate-limit,monitor,tray
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: X11 Applications :: Qt
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt6>=6.5
Dynamic: license-file

<div align="center">

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

<br>

<img src="docs/dongle.png" alt="the dongle" width="240">

<br><br>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5c8bff?style=flat-square" alt="License: MIT"></a>
<img src="https://img.shields.io/badge/python-3.9%2B-5c8bff?style=flat-square" alt="Python 3.9+">
<img src="https://img.shields.io/badge/platform-Linux%20·%20macOS%20·%20Windows-2b2b33?style=flat-square" alt="Platforms">
<img src="https://img.shields.io/badge/UI-PyQt6,%20hand--drawn-2b2b33?style=flat-square" alt="PyQt6">

</div>

---

> **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

<div align="center">
  <img src="docs/rings.gif" alt="usage rings animating" width="440">
  <br>
  <em>The usage gauges, live</em>
</div>

<table>
  <tr>
    <td width="50%"><img src="docs/dashboard.png" alt="dashboard"></td>
    <td width="50%"><img src="docs/dashboard-full.png" alt="dashboard, expanded"></td>
  </tr>
  <tr>
    <td align="center"><em>Dashboard</em></td>
    <td align="center"><em>Forecast, per-model usage and settings, expanded</em></td>
  </tr>
</table>

<div align="center">
  <img src="docs/notifications.png" alt="notifications" width="420">
  <br>
  <em>Limit and overflow-forecast alerts — they fire even with the dongle closed</em>
</div>

See [CHANGELOG.md](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](https://pipx.pypa.io) (recommended — installs into an isolated env):

```bash
pipx install claude-dongle
```

Or with pip:

```bash
pip install --user claude-dongle
```

<details>
<summary>Install the latest unreleased version from source</summary>

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

</details>

Then:

```bash
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

| Command | What it does |
|---|---|
| `claude-dongle tray` | open the floating dongle (normal use) |
| `claude-dongle status` | print the current state as JSON |
| `claude-dongle notify` | check the limits once and notify |
| `claude-dongle config` | open just the settings panel |
| `claude-dongle setup` | set up autostart on login |
| `claude-dongle uninstall` | remove autostart |

**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`:

| Key | Default | Description |
|---|---|---|
| `language` | `"auto"` | `auto` follows your system locale; pin it with `en` or `pt-BR` |
| `thresholds` | `[50, 70, 85, 95]` | percentages that trigger a notification |
| `show_mode` | `"dev"` | when to show the dongle: `always`, `claude`, `dev` or `custom` |
| `poll_interval` | `5` | seconds between dongle refreshes |
| `api_poll_interval` | `300` | minimum interval between API calls (the endpoint rate-limits aggressive polling) |
| `dongle_opacity` | `0.85` | dongle opacity (0 to 1) |
| `battery_saver` | `true` | run every timer at half rate while on battery |
| `notify_on_threshold` | `true` | notify when a threshold is crossed |
| `notify_on_limit` | `true` | notify when 100% is reached |
| `notify_on_reset` | `true` | notify when a spent limit comes back |
| `notify_on_telemetry` | `true` | notify when the monitor loses its data source |
| `forecast_notify` | `true` | notify on a predicted overflow before the reset |
| `notify_cooldown_minutes` | `15` | minimum gap between routine alerts (a limit reached always goes through) |
| `hours_days` | `14` | history window behind the "by hour" profile |
| `reset_day` / `reset_time` / `reset_timezone` | `null` | manual weekly-reset fallback, used only if the API never answered (`null` timezone = system local) |

## 🔍 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:

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

Run the tests:

```bash
pip install pytest
pytest tests/
```

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

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

## 📄 License

MIT © Pedro Henrique — see [LICENSE](LICENSE).
