claude-usage-widget 0.2.2__tar.gz → 0.2.3__tar.gz

{claude_usage_widget-0.2.2/claude_usage_widget.egg-info → claude_usage_widget-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-usage-widget
-Version: 0.2.2
+Version: 0.2.3
 Summary: Desktop widget and CLI that shows real-time Claude Code usage limits and cost.
 Author: Burak
 License: MIT
@@ -68,41 +68,54 @@ A desktop widget that displays your Claude Code usage limits in real time. Shows
 
 ## Installation
 
-### Linux
+### Linux (pip — recommended)
 
 ```bash
-# 1. Install system dependencies (Ubuntu/Debian)
-sudo apt install python3-gi python3-gi-cairo python3-cairo gir1.2-ayatanaappindicator3-0.1
+# 1. Install system GTK stack (one-time)
+sudo apt install python3-gi python3-gi-cairo python3-cairo \
+     gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7   # Ubuntu/Debian
+# Fedora: sudo dnf install python3-gobject python3-gobject-cairo libappindicator-gtk3 libnotify
+# Arch:   sudo pacman -S python-gobject python-cairo libappindicator-gtk3 libnotify
+
+# 2. Install the widget itself
+pip install --user --upgrade claude-usage-widget
 
-# Fedora
-sudo dnf install python3-gobject python3-gobject-cairo python3-cairo gtk3
+# 3. Run
+claude-usage            # launches tray + OSD
+claude-usage --version
+```
 
-# Arch
-sudo pacman -S python-gobject python-cairo gtk3 libappindicator-gtk3
+GNOME users also need the [AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/) for the tray icon.
 
-# 2. Clone and run
+### Linux (from source)
+
+```bash
 git clone https://github.com/bozdemir/claude-usage-widget.git
 cd claude-usage-widget
 python3 main.py &
 
-# 3. Autostart on login (optional)
+# Autostart on login (optional)
 ./install.sh
 ```
 
-### macOS
+### macOS (Homebrew — recommended)
+
+```bash
+brew tap bozdemir/tap
+brew install claude-usage-widget
+claude-usage            # launches menu bar + OSD
+claude-usage --version
+```
+
+### macOS (from source)
 
 ```bash
-# 1. Clone
 git clone https://github.com/bozdemir/claude-usage-widget.git
 cd claude-usage-widget
-
-# 2. Install Python dependencies
 pip3 install -r requirements-macos.txt
-
-# 3. Run
 python3 main.py
 
-# 4. Autostart on login (optional) -- installs a Launch Agent
+# Autostart on login (optional) -- installs a Launch Agent
 ./install-macos.sh
 ```
 

{claude_usage_widget-0.2.2 → claude_usage_widget-0.2.3}/README.md

@@ -39,41 +39,54 @@ A desktop widget that displays your Claude Code usage limits in real time. Shows
 
 ## Installation
 
-### Linux
+### Linux (pip — recommended)
 
 ```bash
-# 1. Install system dependencies (Ubuntu/Debian)
-sudo apt install python3-gi python3-gi-cairo python3-cairo gir1.2-ayatanaappindicator3-0.1
+# 1. Install system GTK stack (one-time)
+sudo apt install python3-gi python3-gi-cairo python3-cairo \
+     gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7   # Ubuntu/Debian
+# Fedora: sudo dnf install python3-gobject python3-gobject-cairo libappindicator-gtk3 libnotify
+# Arch:   sudo pacman -S python-gobject python-cairo libappindicator-gtk3 libnotify
+
+# 2. Install the widget itself
+pip install --user --upgrade claude-usage-widget
 
-# Fedora
-sudo dnf install python3-gobject python3-gobject-cairo python3-cairo gtk3
+# 3. Run
+claude-usage            # launches tray + OSD
+claude-usage --version
+```
 
-# Arch
-sudo pacman -S python-gobject python-cairo gtk3 libappindicator-gtk3
+GNOME users also need the [AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/) for the tray icon.
 
-# 2. Clone and run
+### Linux (from source)
+
+```bash
 git clone https://github.com/bozdemir/claude-usage-widget.git
 cd claude-usage-widget
 python3 main.py &
 
-# 3. Autostart on login (optional)
+# Autostart on login (optional)
 ./install.sh
 ```
 
-### macOS
+### macOS (Homebrew — recommended)
+
+```bash
+brew tap bozdemir/tap
+brew install claude-usage-widget
+claude-usage            # launches menu bar + OSD
+claude-usage --version
+```
+
+### macOS (from source)
 
 ```bash
-# 1. Clone
 git clone https://github.com/bozdemir/claude-usage-widget.git
 cd claude-usage-widget
-
-# 2. Install Python dependencies
 pip3 install -r requirements-macos.txt
-
-# 3. Run
 python3 main.py
 
-# 4. Autostart on login (optional) -- installs a Launch Agent
+# Autostart on login (optional) -- installs a Launch Agent
 ./install-macos.sh
 ```
 

{claude_usage_widget-0.2.2 → claude_usage_widget-0.2.3}/claude_usage/__init__.py

@@ -1,3 +1,3 @@
 """Claude Usage Widget — desktop usage tracker for Claude Code."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"

{claude_usage_widget-0.2.2 → claude_usage_widget-0.2.3}/claude_usage/notifier.py

@@ -5,6 +5,7 @@ binds the detector to a platform-appropriate desktop notification sender.
 """
 
 import sys
+from typing import Callable, Optional
 
 
 class CrossingDetector:
@@ -58,21 +59,37 @@ class UsageNotifier:
         ("weekly", "Weekly", "weekly_utilization"),
     )
 
-    def __init__(self, config: dict, sender=None):
+    def __init__(
+        self,
+        config: dict,
+        sender: Optional[Callable[[str, str], None]] = None,
+        on_threshold: Optional[Callable[[str, float], None]] = None,
+    ):
         self.enabled = bool(config.get("notifications_enabled", True))
         thresholds = config.get("notify_thresholds", [0.75, 0.90])
         self.detector = CrossingDetector(thresholds)
         self._send = sender or _default_sender()
+        # Observer callback fired for every threshold crossing, used e.g.
+        # by the widget to dispatch a webhook. Fires independent of the
+        # ``enabled`` flag — webhooks are a separate opt-in pathway.
+        self._on_threshold = on_threshold
 
     def check_stats(self, stats) -> None:
-        if not self.enabled:
-            return
         for scope, label, attr in self.SCOPES:
             util = getattr(stats, attr, 0.0) or 0.0
-            for t in self.detector.check(scope, util):
-                pct_t = int(round(t * 100))
-                pct_now = int(round(util * 100))
-                self._send(
-                    f"Claude {label} usage at {pct_now}%",
-                    f"Crossed the {pct_t}% threshold.",
-                )
+            crossings = self.detector.check(scope, util)
+            for t in crossings:
+                # Desktop notification (respects notifications_enabled)
+                if self.enabled:
+                    pct_t = int(round(t * 100))
+                    pct_now = int(round(util * 100))
+                    self._send(
+                        f"Claude {label} usage at {pct_now}%",
+                        f"Crossed the {pct_t}% threshold.",
+                    )
+                # Observer callback (independent of notifications_enabled)
+                if self._on_threshold is not None:
+                    try:
+                        self._on_threshold(scope, t)
+                    except Exception:
+                        pass

{claude_usage_widget-0.2.2 → claude_usage_widget-0.2.3}/claude_usage/widget.py

@@ -759,13 +759,21 @@ class ClaudeUsageTray:
         self.popup: UsagePopup = UsagePopup(config)
         self.overlay: UsageOverlay = UsageOverlay(config)
         self.overlay.show_all()
-        self.notifier = UsageNotifier(config)
 
         # Webhook dispatcher — fires on threshold / daily / anomaly events.
         from claude_usage.webhooks import WebhookDispatcher
         self._webhooks = WebhookDispatcher(config.get("webhooks", {}))
         self._last_daily_report_date: str = ""
 
+        # Notifier must be constructed after _webhooks so its on_threshold
+        # callback can dispatch to the webhook.
+        self.notifier = UsageNotifier(
+            config,
+            on_threshold=lambda scope, t: self._webhooks.fire(
+                "threshold_crossed", {"scope": scope, "threshold": t},
+            ),
+        )
+
         # Optional: start localhost JSON API server for shell integrations.
         self._api_server = None
         if config.get("api_server_enabled"):

{claude_usage_widget-0.2.2 → claude_usage_widget-0.2.3}/claude_usage/widget_macos.py

@@ -1032,13 +1032,21 @@ class ClaudeUsageTray(rumps.App):
         self.popup  = UsagePopup()
         self.overlay = UsageOverlay(config)
         self.overlay.show_all()
-        self.notifier = UsageNotifier(config)
 
         # Webhook dispatcher — fires on threshold / daily / anomaly events.
         from claude_usage.webhooks import WebhookDispatcher
         self._webhooks = WebhookDispatcher(config.get("webhooks", {}))
         self._last_daily_report_date: str = ""
 
+        # Notifier must be constructed after _webhooks so its on_threshold
+        # callback can dispatch to the webhook.
+        self.notifier = UsageNotifier(
+            config,
+            on_threshold=lambda scope, t: self._webhooks.fire(
+                "threshold_crossed", {"scope": scope, "threshold": t},
+            ),
+        )
+
         # Optional: start localhost JSON API server for shell integrations.
         self._api_server = None
         if config.get("api_server_enabled"):

{claude_usage_widget-0.2.2 → claude_usage_widget-0.2.3/claude_usage_widget.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-usage-widget
-Version: 0.2.2
+Version: 0.2.3
 Summary: Desktop widget and CLI that shows real-time Claude Code usage limits and cost.
 Author: Burak
 License: MIT
@@ -68,41 +68,54 @@ A desktop widget that displays your Claude Code usage limits in real time. Shows
 
 ## Installation
 
-### Linux
+### Linux (pip — recommended)
 
 ```bash
-# 1. Install system dependencies (Ubuntu/Debian)
-sudo apt install python3-gi python3-gi-cairo python3-cairo gir1.2-ayatanaappindicator3-0.1
+# 1. Install system GTK stack (one-time)
+sudo apt install python3-gi python3-gi-cairo python3-cairo \
+     gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7   # Ubuntu/Debian
+# Fedora: sudo dnf install python3-gobject python3-gobject-cairo libappindicator-gtk3 libnotify
+# Arch:   sudo pacman -S python-gobject python-cairo libappindicator-gtk3 libnotify
+
+# 2. Install the widget itself
+pip install --user --upgrade claude-usage-widget
 
-# Fedora
-sudo dnf install python3-gobject python3-gobject-cairo python3-cairo gtk3
+# 3. Run
+claude-usage            # launches tray + OSD
+claude-usage --version
+```
 
-# Arch
-sudo pacman -S python-gobject python-cairo gtk3 libappindicator-gtk3
+GNOME users also need the [AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/) for the tray icon.
 
-# 2. Clone and run
+### Linux (from source)
+
+```bash
 git clone https://github.com/bozdemir/claude-usage-widget.git
 cd claude-usage-widget
 python3 main.py &
 
-# 3. Autostart on login (optional)
+# Autostart on login (optional)
 ./install.sh
 ```
 
-### macOS
+### macOS (Homebrew — recommended)
+
+```bash
+brew tap bozdemir/tap
+brew install claude-usage-widget
+claude-usage            # launches menu bar + OSD
+claude-usage --version
+```
+
+### macOS (from source)
 
 ```bash
-# 1. Clone
 git clone https://github.com/bozdemir/claude-usage-widget.git
 cd claude-usage-widget
-
-# 2. Install Python dependencies
 pip3 install -r requirements-macos.txt
-
-# 3. Run
 python3 main.py
 
-# 4. Autostart on login (optional) -- installs a Launch Agent
+# Autostart on login (optional) -- installs a Launch Agent
 ./install-macos.sh
 ```