claude-dongle 1.0.0__tar.gz

claude_dongle-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+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.

claude_dongle-1.0.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: claude-dongle
+Version: 1.0.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: 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: 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
+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 pulses amber when, at the
+  current pace, you'll run out before the reset.
+- **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-project & per-model usage** — from Claude Code's local logs, it shows
+  which projects and models ate your week (with a 14-day heatmap).
+- **Limit notifications** — alerts when you cross a threshold and on the overflow
+  forecast. Works even with the dongle closed, via a background timer.
+- **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 &amp; per-project usage, 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>
+
+## 📦 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 git+https://github.com/PedroHenrique0713/claude-dongle
+```
+
+Or with pip:
+
+```bash
+pip install --user git+https://github.com/PedroHenrique0713/claude-dongle
+```
+
+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.
+
+## 🔧 Configuration
+
+Tune it from the panel or by editing `~/.config/claude-dongle/config.json`:
+
+| Key | Default | Description |
+|---|---|---|
+| `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) |
+| `notify_on_threshold` | `true` | notify when a threshold is crossed |
+| `notify_on_limit` | `true` | notify when 100% is reached |
+| `forecast_notify` | `true` | notify on a predicted overflow before the reset |
+| `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 project/model by reading the JSONL files in
+  `~/.claude/projects`.
+- `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).

claude_dongle-1.0.0/README.md

@@ -0,0 +1,181 @@
+<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 pulses amber when, at the
+  current pace, you'll run out before the reset.
+- **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-project & per-model usage** — from Claude Code's local logs, it shows
+  which projects and models ate your week (with a 14-day heatmap).
+- **Limit notifications** — alerts when you cross a threshold and on the overflow
+  forecast. Works even with the dongle closed, via a background timer.
+- **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 &amp; per-project usage, 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>
+
+## 📦 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 git+https://github.com/PedroHenrique0713/claude-dongle
+```
+
+Or with pip:
+
+```bash
+pip install --user git+https://github.com/PedroHenrique0713/claude-dongle
+```
+
+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.
+
+## 🔧 Configuration
+
+Tune it from the panel or by editing `~/.config/claude-dongle/config.json`:
+
+| Key | Default | Description |
+|---|---|---|
+| `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) |
+| `notify_on_threshold` | `true` | notify when a threshold is crossed |
+| `notify_on_limit` | `true` | notify when 100% is reached |
+| `forecast_notify` | `true` | notify on a predicted overflow before the reset |
+| `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 project/model by reading the JSONL files in
+  `~/.claude/projects`.
+- `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).

claude_dongle-1.0.0/claude_dongle/__init__.py

@@ -0,0 +1,2 @@
+"""claude-dongle — Claude Code rate-limit monitor (floating dongle + dashboard)."""
+__version__ = "1.0.0"

claude_dongle-1.0.0/claude_dongle/__main__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+main()

claude_dongle-1.0.0/claude_dongle/autostart.py

@@ -0,0 +1,176 @@
+"""Install/remove the dongle's login autostart, per operating system:
+Linux (systemd user), macOS (LaunchAgent), Windows (Startup folder)."""
+import os
+import sys
+import shutil
+import subprocess
+from pathlib import Path
+
+_LABEL = "com.claudedongle.dongle"
+# Pre-rename artifacts (the project used to be called claude-monitor):
+# removed on install/uninstall so both autostarts never run side by side.
+_LEGACY_LABEL = "com.claudemonitor.dongle"
+_LEGACY_UNITS = ("claude-monitor.service", "claude-monitor-notify.service",
+                 "claude-monitor-notify.timer")
+
+
+def _tray_cmd():
+    """Command that starts the dongle. Prefers the installed console script;
+    falls back to the module. On Windows uses pythonw (no console window)."""
+    exe = shutil.which("claude-dongle")
+    if exe and sys.platform != "win32":
+        return [exe, "tray"]
+    py = sys.executable
+    if sys.platform == "win32":
+        pyw = Path(py).with_name("pythonw.exe")
+        py = str(pyw) if pyw.exists() else py
+    return [py, "-m", "claude_dongle", "tray"]
+
+
+# ---------- Linux (systemd --user) ----------
+
+def _linux_unit_dir():
+    return Path.home() / ".config" / "systemd" / "user"
+
+
+def _cleanup_legacy_linux():
+    d = _linux_unit_dir()
+    if not any((d / u).exists() for u in _LEGACY_UNITS):
+        return
+    for unit in ("claude-monitor.service", "claude-monitor-notify.timer"):
+        subprocess.run(["systemctl", "--user", "disable", "--now", unit],
+                       check=False, capture_output=True)
+    for f in _LEGACY_UNITS:
+        (d / f).unlink(missing_ok=True)
+
+
+def _install_linux():
+    _cleanup_legacy_linux()
+    d = _linux_unit_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    exec_start = " ".join(_tray_cmd())
+    (d / "claude-dongle.service").write_text(
+        "[Unit]\n"
+        "Description=Claude Code usage monitor — dongle\n"
+        "After=graphical-session.target\n"
+        "PartOf=graphical-session.target\n\n"
+        "[Service]\nType=simple\n"
+        f"ExecStart={exec_start}\n"
+        "Restart=on-failure\nRestartSec=5\n\n"
+        "[Install]\nWantedBy=graphical-session.target\n")
+    notify = " ".join(_tray_cmd()[:-1] + ["notify"])
+    (d / "claude-dongle-notify.service").write_text(
+        "[Unit]\nDescription=Claude Code usage monitor — limit check\n"
+        "After=graphical-session.target\n\n"
+        f"[Service]\nType=oneshot\nExecStart={notify}\n")
+    (d / "claude-dongle-notify.timer").write_text(
+        "[Unit]\nDescription=Checks Claude Code limits periodically\n\n"
+        "[Timer]\nOnBootSec=2min\nOnUnitActiveSec=10min\nPersistent=true\n\n"
+        "[Install]\nWantedBy=timers.target\n")
+    subprocess.run(["systemctl", "--user", "daemon-reload"], check=False)
+    subprocess.run(["systemctl", "--user", "enable", "--now",
+                    "claude-dongle.service"], check=False)
+    subprocess.run(["systemctl", "--user", "enable", "--now",
+                    "claude-dongle-notify.timer"], check=False)
+    return "systemd user service enabled (starts on login)."
+
+
+def _uninstall_linux():
+    _cleanup_legacy_linux()
+    for unit in ("claude-dongle.service", "claude-dongle-notify.timer"):
+        subprocess.run(["systemctl", "--user", "disable", "--now", unit],
+                       check=False)
+    d = _linux_unit_dir()
+    for f in ("claude-dongle.service", "claude-dongle-notify.service",
+              "claude-dongle-notify.timer"):
+        (d / f).unlink(missing_ok=True)
+    subprocess.run(["systemctl", "--user", "daemon-reload"], check=False)
+    return "systemd user service removed."
+
+
+# ---------- macOS (LaunchAgent) ----------
+
+def _mac_plist(label=_LABEL):
+    return Path.home() / "Library" / "LaunchAgents" / f"{label}.plist"
+
+
+def _cleanup_legacy_mac():
+    p = _mac_plist(_LEGACY_LABEL)
+    if p.exists():
+        subprocess.run(["launchctl", "unload", str(p)], check=False,
+                       capture_output=True)
+        p.unlink(missing_ok=True)
+
+
+def _install_mac():
+    _cleanup_legacy_mac()
+    p = _mac_plist()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    args = "".join(f"<string>{a}</string>" for a in _tray_cmd())
+    p.write_text(
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" '
+        '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
+        '<plist version="1.0"><dict>\n'
+        f'  <key>Label</key><string>{_LABEL}</string>\n'
+        f'  <key>ProgramArguments</key><array>{args}</array>\n'
+        '  <key>RunAtLoad</key><true/>\n'
+        '  <key>KeepAlive</key><true/>\n'
+        '</dict></plist>\n')
+    subprocess.run(["launchctl", "unload", str(p)], check=False,
+                   capture_output=True)
+    subprocess.run(["launchctl", "load", str(p)], check=False)
+    return "LaunchAgent installed (starts on login)."
+
+
+def _uninstall_mac():
+    _cleanup_legacy_mac()
+    p = _mac_plist()
+    subprocess.run(["launchctl", "unload", str(p)], check=False,
+                   capture_output=True)
+    p.unlink(missing_ok=True)
+    return "LaunchAgent removed."
+
+
+# ---------- Windows (Startup folder) ----------
+
+def _win_startup_bat(name="claude-dongle.bat"):
+    base = os.environ.get("APPDATA", str(Path.home() / "AppData" / "Roaming"))
+    return (Path(base) / "Microsoft" / "Windows" / "Start Menu" /
+            "Programs" / "Startup" / name)
+
+
+def _install_windows():
+    _win_startup_bat("claude-monitor.bat").unlink(missing_ok=True)  # legacy
+    bat = _win_startup_bat()
+    bat.parent.mkdir(parents=True, exist_ok=True)
+    cmd = " ".join(f'"{a}"' if " " in a else a for a in _tray_cmd())
+    bat.write_text(f'@start "" {cmd}\r\n')
+    subprocess.Popen(_tray_cmd())  # start now, without waiting for next login
+    return "shortcut in the Startup folder (starts on login)."
+
+
+def _uninstall_windows():
+    _win_startup_bat("claude-monitor.bat").unlink(missing_ok=True)  # legacy
+    _win_startup_bat().unlink(missing_ok=True)
+    return "Startup folder shortcut removed."
+
+
+def install():
+    if sys.platform.startswith("linux"):
+        return _install_linux()
+    if sys.platform == "darwin":
+        return _install_mac()
+    if sys.platform == "win32":
+        return _install_windows()
+    raise RuntimeError(f"unsupported platform: {sys.platform}")
+
+
+def uninstall():
+    if sys.platform.startswith("linux"):
+        return _uninstall_linux()
+    if sys.platform == "darwin":
+        return _uninstall_mac()
+    if sys.platform == "win32":
+        return _uninstall_windows()
+    raise RuntimeError(f"unsupported platform: {sys.platform}")

claude_dongle-1.0.0/claude_dongle/config.py

@@ -0,0 +1,63 @@
+import json
+import shutil
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".config" / "claude-dongle"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+# Pre-rename config dir (the project used to be called claude-monitor):
+# copied once, on first load, so settings/history survive the rename.
+LEGACY_CONFIG_DIR = Path.home() / ".config" / "claude-monitor"
+
+DEFAULTS = {
+    # Manual fallback for the weekly reset, used only when the API never
+    # answered (it normally provides the real resets_at). null = unknown:
+    # the UI shows "--" instead of guessing. Example: "thursday", "18:00",
+    # "America/New_York" (reset_timezone null = system local timezone).
+    "reset_day": None,
+    "reset_time": None,
+    "reset_timezone": None,
+    "poll_interval": 5,
+    "thresholds": [50, 70, 85, 95],
+    "notify_on_threshold": True,
+    "notify_on_limit": True,
+    "telemetry_stale_minutes": 60,  # no fresh data for X min → warn once
+    "claude_dir": str(Path.home() / ".claude"),
+    "dongle_opacity": 0.85,
+    "dongle_always_on_top": True,
+    "dongle_pos": None,  # [x, y] of the last dragged position (null = default corner)
+    "show_mode": "dev",
+    "idle_quit_minutes": 10,  # hidden for X min → the service exits (0 = never)
+    "show_processes": ["code", "claude"],  # process names for show_mode=custom
+    "api_poll_interval": 300,  # the usage endpoint rate-limits aggressive polling
+    "history_retention_days": 21,  # burn-rate time series (GC'd on start)
+    "burn_lookback_minutes": 60,   # burn-rate regression window
+    "burn_min_points": 3,          # minimum points to show a forecast
+    "forecast_notify": True,       # notify on predicted overflow before the reset
+    "forecast_expanded": False,    # Forecast section starts collapsed
+    "projects_expanded": False,    # "By project" section starts collapsed
+}
+
+
+def _migrate_legacy():
+    if CONFIG_DIR.exists() or not LEGACY_CONFIG_DIR.exists():
+        return
+    try:
+        shutil.copytree(LEGACY_CONFIG_DIR, CONFIG_DIR)
+    except OSError:
+        pass
+
+
+def load():
+    _migrate_legacy()
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    if CONFIG_PATH.exists():
+        merged = DEFAULTS.copy()
+        merged.update(json.loads(CONFIG_PATH.read_text()))
+        return merged
+    save(DEFAULTS)
+    return DEFAULTS.copy()
+
+
+def save(cfg):
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(json.dumps(cfg, indent=2))