claude-code-usage 1.0.0__py3-none-any.whl

src/config.py

@@ -0,0 +1,173 @@
+"""Configuration module for loading Claude OAuth credentials."""
+
+import json
+import os
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+CREDENTIALS_PATH = Path.home() / ".claude" / ".credentials.json"
+
+
+def load_credentials() -> dict:
+    """Load Claude OAuth credentials from ~/.claude/.credentials.json.
+
+    Returns:
+        dict: The claudeAiOauth object containing accessToken, expiresAt, etc.
+
+    Raises:
+        FileNotFoundError: If credentials file doesn't exist
+        ValueError: If credentials file format is invalid
+    """
+    if not CREDENTIALS_PATH.exists():
+        raise FileNotFoundError(
+            "Claude credentials not found. Run `claude` first to authenticate."
+        )
+
+    try:
+        with open(CREDENTIALS_PATH, 'r') as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid credentials file format: {e}")
+
+    if "claudeAiOauth" not in data:
+        raise ValueError("Invalid credentials file format")
+
+    return data["claudeAiOauth"]
+
+
+def is_token_expired(credentials: dict) -> bool:
+    """Check if the OAuth token has expired.
+
+    Args:
+        credentials: The claudeAiOauth object with expiresAt field
+
+    Returns:
+        bool: True if expired or expiresAt is None
+    """
+    expires_at = credentials.get("expiresAt")
+
+    if expires_at is None:
+        return True
+
+    # expiresAt is in milliseconds since epoch
+    current_time_ms = time.time() * 1000
+    return current_time_ms >= expires_at
+
+
+def get_access_token() -> str:
+    """Get a valid OAuth access token.
+
+    Returns:
+        str: The access token string
+
+    Raises:
+        FileNotFoundError: If credentials file doesn't exist
+        ValueError: If credentials are invalid or token expired
+    """
+    credentials = load_credentials()
+
+    if is_token_expired(credentials):
+        raise ValueError("OAuth token has expired")
+
+    return credentials["accessToken"]
+
+
+def get_config_path() -> Path:
+    """Get XDG-compliant config file path.
+
+    Returns:
+        Path: Path to config.json in XDG config directory
+    """
+    config_home = os.environ.get('XDG_CONFIG_HOME')
+    if config_home:
+        base = Path(config_home)
+    else:
+        base = Path.home() / '.config'
+
+    config_dir = base / 'claude-usage-overlay'
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    return config_dir / 'config.json'
+
+
+@dataclass
+class UserConfig:
+    """User configuration settings for Claude Usage Overlay."""
+
+    session_thresholds: list[int] = None
+    weekly_thresholds: list[int] = None
+    polling_interval: int = 300
+    pause_notifications: bool = False
+    autostart_enabled: bool = False
+
+    def __post_init__(self):
+        """Validate configuration values and set defaults."""
+        # Set defaults for None fields (avoid mutable default trap)
+        if self.session_thresholds is None:
+            self.session_thresholds = [50, 75, 90]
+        if self.weekly_thresholds is None:
+            self.weekly_thresholds = [50, 75, 90]
+
+        # Validate thresholds
+        for threshold in self.session_thresholds:
+            if not isinstance(threshold, int) or not (0 <= threshold <= 100):
+                raise ValueError(
+                    f"Invalid session threshold: {threshold}. Must be integer 0-100."
+                )
+        for threshold in self.weekly_thresholds:
+            if not isinstance(threshold, int) or not (0 <= threshold <= 100):
+                raise ValueError(
+                    f"Invalid weekly threshold: {threshold}. Must be integer 0-100."
+                )
+
+        # Validate polling_interval
+        if not isinstance(self.polling_interval, int) or not (30 <= self.polling_interval <= 3600):
+            raise ValueError(
+                f"Invalid polling_interval: {self.polling_interval}. Must be integer 30-3600."
+            )
+
+        # Validate boolean fields
+        if not isinstance(self.pause_notifications, bool):
+            raise ValueError(
+                f"Invalid pause_notifications: {self.pause_notifications}. Must be bool."
+            )
+        if not isinstance(self.autostart_enabled, bool):
+            raise ValueError(
+                f"Invalid autostart_enabled: {self.autostart_enabled}. Must be bool."
+            )
+
+    @classmethod
+    def load(cls) -> 'UserConfig':
+        """Load configuration from XDG config file.
+
+        Returns:
+            UserConfig: Configuration object with values from file or defaults
+
+        Raises:
+            ValueError: If config file format is invalid
+        """
+        config_path = get_config_path()
+
+        if not config_path.exists():
+            return cls()
+
+        try:
+            with open(config_path, 'r') as f:
+                data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid config file format: {e}")
+
+        try:
+            return cls(**data)
+        except TypeError as e:
+            raise ValueError(f"Invalid config file structure: {e}")
+
+    def save(self):
+        """Save configuration to XDG config file."""
+        config_path = get_config_path()
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(config_path, 'w') as f:
+            json.dump(asdict(self), f, indent=2)

src/icon_generator.py

@@ -0,0 +1,92 @@
+"""
+Icon generation utilities for Claude Code usage overlay.
+
+Generates circular gauge icons using Cairo for system tray display.
+"""
+import cairo
+import math
+import os
+from typing import Tuple
+
+
+def get_color_for_percentage(percentage: float) -> Tuple[float, float, float]:
+    """
+    Return RGB color tuple based on usage percentage.
+
+    Args:
+        percentage: Usage percentage (0-100)
+
+    Returns:
+        RGB tuple in Cairo format (0.0-1.0 range)
+        - Green for < 50%
+        - Yellow for 50-75%
+        - Red for >= 75%
+    """
+    if percentage < 50:
+        return (0.2, 0.8, 0.2)  # Green
+    elif percentage < 75:
+        return (0.9, 0.7, 0.0)  # Yellow
+    else:
+        return (0.9, 0.2, 0.2)  # Red
+
+
+def generate_gauge_icon(percentage: float, color_percentage: float, size: int = 22) -> str:
+    """
+    Generate a circular gauge icon showing usage percentage.
+
+    Args:
+        percentage: Usage level to display as arc fill (0-100)
+        color_percentage: Percentage used to determine color (0-100)
+        size: Icon size in pixels (default: 22)
+
+    Returns:
+        Absolute path to generated PNG file in /tmp
+
+    Notes:
+        - percentage controls the arc fill amount (how full the gauge is)
+        - color_percentage controls the color (via get_color_for_percentage)
+        - This separation allows showing session usage while coloring by worst-case urgency
+    """
+    # Get color based on color_percentage parameter
+    fill_color = get_color_for_percentage(color_percentage)
+
+    # Determine color name for filename (to bust icon cache)
+    if color_percentage < 50:
+        color_name = "green"
+    elif color_percentage < 75:
+        color_name = "yellow"
+    else:
+        color_name = "red"
+
+    # Create Cairo surface with transparent background
+    surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, size, size)
+    ctx = cairo.Context(surface)
+
+    # Clear background (transparent)
+    ctx.set_source_rgba(0, 0, 0, 0)
+    ctx.paint()
+
+    # Calculate center and radius (leave 2px margin)
+    center = size / 2
+    radius = (size / 2) - 2
+
+    # Draw gray outline (full circle)
+    ctx.set_source_rgb(0.5, 0.5, 0.5)
+    ctx.set_line_width(2)
+    ctx.arc(center, center, radius, 0, 2 * math.pi)
+    ctx.stroke()
+
+    # Draw colored fill arc (based on percentage)
+    if percentage > 0:
+        ctx.set_source_rgb(*fill_color)
+        ctx.set_line_width(2)
+        # Start at 12 o'clock (-pi/2), go clockwise by percentage amount
+        end_angle = -math.pi / 2 + (2 * math.pi * percentage / 100)
+        ctx.arc(center, center, radius, -math.pi / 2, end_angle)
+        ctx.stroke()
+
+    # Save to unique filename per percentage and color state (bust GTK icon cache)
+    icon_path = f"/tmp/claude-usage-{int(percentage)}-{color_name}.png"
+    surface.write_to_png(icon_path)
+
+    return os.path.abspath(icon_path)

src/main.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""Claude Code Usage Overlay - System tray application."""
+
+import sys
+
+
+def main():
+    """Start the Claude Code Usage Overlay application."""
+    try:
+        from src.tray import TrayIndicator
+
+        indicator = TrayIndicator()
+        indicator.run()
+
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+        sys.exit(0)
+    except Exception as e:
+        print(f"Fatal error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

src/notifier.py

@@ -0,0 +1,289 @@
+"""Desktop notification manager for usage threshold alerts."""
+
+import subprocess
+import time
+
+import gi
+
+gi.require_version('Notify', '0.7')
+from gi.repository import Notify
+
+
+class UsageNotifier:
+    """Manages threshold-based usage notifications.
+
+    Displays popup notifications when session or weekly usage crosses
+    thresholds (50%, 75%, 90%) with escalating urgency and advice.
+    Tracks alerted thresholds to prevent notification spam.
+    """
+
+    def __init__(self, app_name="Claude Code Usage Monitor",
+                 session_thresholds=None, weekly_thresholds=None):
+        """Initialize the notifier.
+
+        Args:
+            app_name: Name shown in notification server
+            session_thresholds: List of threshold percentages for session (default [50, 75, 90])
+            weekly_thresholds: List of threshold percentages for weekly (default to session_thresholds)
+        """
+        # Initialize libnotify once
+        Notify.init(app_name)
+
+        # Configure thresholds
+        self.session_thresholds = session_thresholds if session_thresholds is not None else [50, 75, 90]
+        self.weekly_thresholds = weekly_thresholds if weekly_thresholds is not None else self.session_thresholds
+
+        # Track alerted thresholds: {(metric, threshold): True}
+        # metric = 'session' or 'weekly'
+        # threshold = 50, 75, or 90
+        self.alerted = {}
+
+        # Grace period flag - skip first poll to avoid startup spam
+        self.first_poll = True
+
+        # Pause notifications mode
+        self.pause_notifications = False
+
+        # Cache server capabilities
+        self._actions_supported = None
+
+    def check_and_notify(self, session_pct, weekly_pct, session_reset, weekly_reset):
+        """Check thresholds and show notifications if needed.
+
+        Main entry point called by TrayIndicator after each usage update.
+
+        Args:
+            session_pct: Session usage percentage (0-100)
+            weekly_pct: Weekly usage percentage (0-100)
+            session_reset: Unix timestamp when session resets
+            weekly_reset: Unix timestamp when weekly resets
+        """
+        # Skip first poll (grace period)
+        if self.first_poll:
+            self.first_poll = False
+            return
+
+        # Respect pause mode
+        if self.pause_notifications:
+            return
+
+        # Find highest threshold crossed for each metric
+        session_threshold = self._highest_crossed(session_pct, self.session_thresholds)
+        weekly_threshold = self._highest_crossed(weekly_pct, self.weekly_thresholds)
+
+        # Determine if we should alert
+        session_needs_alert = (
+            session_threshold and
+            ('session', session_threshold) not in self.alerted
+        )
+        weekly_needs_alert = (
+            weekly_threshold and
+            ('weekly', weekly_threshold) not in self.alerted
+        )
+
+        # Handle combined case first (both need alerts)
+        if session_needs_alert and weekly_needs_alert:
+            if session_threshold == weekly_threshold:
+                # Same threshold - use that urgency
+                self._show_combined_notification(
+                    session_threshold, session_pct, weekly_pct,
+                    session_reset, weekly_reset
+                )
+            else:
+                # Different thresholds - use highest urgency
+                max_threshold = max(session_threshold, weekly_threshold)
+                self._show_combined_notification(
+                    max_threshold, session_pct, weekly_pct,
+                    session_reset, weekly_reset
+                )
+            # Mark both as alerted
+            self.alerted[('session', session_threshold)] = True
+            self.alerted[('weekly', weekly_threshold)] = True
+
+        # Individual alerts
+        elif session_needs_alert:
+            self._show_notification(
+                'session', session_pct, session_threshold, session_reset
+            )
+            self.alerted[('session', session_threshold)] = True
+
+        elif weekly_needs_alert:
+            self._show_notification(
+                'weekly', weekly_pct, weekly_threshold, weekly_reset
+            )
+            self.alerted[('weekly', weekly_threshold)] = True
+
+    def _highest_crossed(self, percentage, thresholds):
+        """Return highest threshold crossed, or None.
+
+        Args:
+            percentage: Current usage percentage (0-100)
+            thresholds: List of threshold values to check
+
+        Returns:
+            int: Highest crossed threshold, or None if no thresholds crossed
+        """
+        crossed = [t for t in thresholds if percentage >= t]
+        return max(crossed) if crossed else None
+
+    def _show_notification(self, metric, percentage, threshold, reset_time):
+        """Show notification for single metric threshold.
+
+        Args:
+            metric: 'session' or 'weekly'
+            percentage: Current usage percentage (0-100)
+            threshold: Threshold that was crossed (50, 75, or 90)
+            reset_time: Unix timestamp when metric resets
+        """
+        # Map threshold to urgency and advice
+        urgency_map = {
+            50: (Notify.Urgency.LOW, "Heads up"),
+            75: (Notify.Urgency.NORMAL, "Consider saving your work"),
+            90: (Notify.Urgency.CRITICAL, "Save your work now")
+        }
+
+        urgency, advice = urgency_map[threshold]
+
+        # Format title
+        metric_name = "Session Usage" if metric == 'session' else "Weekly Usage"
+        title = f"{metric_name}: {percentage:.0f}%"
+
+        # Format body with reset time
+        reset_str = self._format_reset_time(reset_time)
+        body = f"{advice}\n\nResets in {reset_str}"
+
+        # Create notification
+        notification = Notify.Notification.new(
+            title,
+            body,
+            "dialog-information"
+        )
+
+        # Set urgency level
+        notification.set_urgency(urgency)
+
+        # Add action button if server supports it
+        if self._server_supports_actions():
+            notification.add_action(
+                "open-claude",
+                "Open Claude Code",
+                self._on_open_claude,
+                None
+            )
+
+        # Show notification
+        notification.show()
+
+    def _show_combined_notification(self, threshold, session_pct, weekly_pct,
+                                    session_reset, weekly_reset):
+        """Show combined notification for both metrics.
+
+        Args:
+            threshold: Threshold to use for urgency (highest of both)
+            session_pct: Session usage percentage (0-100)
+            weekly_pct: Weekly usage percentage (0-100)
+            session_reset: Unix timestamp when session resets
+            weekly_reset: Unix timestamp when weekly resets
+        """
+        # Map threshold to urgency and advice
+        urgency_map = {
+            50: (Notify.Urgency.LOW, "Heads up"),
+            75: (Notify.Urgency.NORMAL, "Consider saving your work"),
+            90: (Notify.Urgency.CRITICAL, "Save your work now")
+        }
+
+        urgency, advice = urgency_map[threshold]
+
+        # Format title (show threshold, not individual percentages)
+        title = f"Session & Weekly Usage: {threshold}%"
+
+        # Format body with both reset times
+        session_reset_str = self._format_reset_time(session_reset)
+        weekly_reset_str = self._format_reset_time(weekly_reset)
+        body = (f"{advice}\n\n"
+                f"Session resets in {session_reset_str}\n"
+                f"Weekly resets in {weekly_reset_str}")
+
+        # Create notification
+        notification = Notify.Notification.new(
+            title,
+            body,
+            "dialog-information"
+        )
+
+        # Set urgency level
+        notification.set_urgency(urgency)
+
+        # Add action button if server supports it
+        if self._server_supports_actions():
+            notification.add_action(
+                "open-claude",
+                "Open Claude Code",
+                self._on_open_claude,
+                None
+            )
+
+        # Show notification
+        notification.show()
+
+    def _format_reset_time(self, reset_timestamp):
+        """Format Unix timestamp to human-readable time until reset.
+
+        Args:
+            reset_timestamp: Unix timestamp (seconds since epoch)
+
+        Returns:
+            str: Human-readable time string (e.g., "2h", "3d", "45m")
+        """
+        now = time.time()
+        seconds = int(reset_timestamp - now)
+
+        if seconds <= 0:
+            return "shortly"
+
+        # Convert to hours and days using divmod
+        hours, remainder = divmod(seconds, 3600)
+        days, hours = divmod(hours, 24)
+
+        if days > 0:
+            return f"{days}d"
+        elif hours > 0:
+            return f"{hours}h"
+        else:
+            minutes = remainder // 60
+            return f"{minutes}m" if minutes > 0 else "shortly"
+
+    def _server_supports_actions(self):
+        """Check if notification server supports action buttons.
+
+        Returns:
+            bool: True if server supports actions, False otherwise
+        """
+        if self._actions_supported is None:
+            caps = Notify.get_server_caps()
+            self._actions_supported = caps and 'actions' in caps
+        return self._actions_supported
+
+    def _on_open_claude(self, notification, action, user_data):
+        """Callback when 'Open Claude Code' button is clicked.
+
+        Args:
+            notification: The notification that triggered the action
+            action: Action identifier string
+            user_data: User data passed to add_action (unused)
+        """
+        # Close the notification
+        notification.close()
+
+        # Open Claude Code in browser
+        subprocess.Popen(["/usr/bin/xdg-open", "https://claude.ai"])
+
+    def set_thresholds(self, session_thresholds, weekly_thresholds=None):
+        """Update threshold configuration.
+
+        Args:
+            session_thresholds: List of session threshold percentages
+            weekly_thresholds: List of weekly threshold percentages (defaults to session)
+        """
+        self.session_thresholds = session_thresholds
+        self.weekly_thresholds = weekly_thresholds if weekly_thresholds is not None else session_thresholds