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

claude_code_usage-1.0.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: claude-code-usage
+Version: 1.0.0
+Summary: System tray monitor for Claude Code token usage
+Author: Max
+License: MIT
+Project-URL: Homepage, https://github.com/Maex-z9/CC_Usage
+Project-URL: Repository, https://github.com/Maex-z9/CC_Usage
+Project-URL: Issues, https://github.com/Maex-z9/CC_Usage/issues
+Keywords: claude,anthropic,usage,monitor,tray,gnome
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications :: GTK
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: PyGObject>=3.42.0
+Dynamic: license-file
+
+# Claude Code Usage Overlay
+
+A Linux/GNOME system tray application that monitors your Claude Code token usage and alerts you before hitting limits.
+
+![Python](https://img.shields.io/badge/python-3.11+-blue.svg)
+![Platform](https://img.shields.io/badge/platform-Linux%2FGNOME-lightgrey.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+
+## Features
+
+- **System tray icon** with color-coded gauge (green/yellow/red based on usage)
+- **Panel label** showing session and weekly usage percentages
+- **Popup notifications** at configurable thresholds (default: 50%, 75%, 90%)
+- **Configurable settings** via JSON file or Settings menu
+- **Auto-start on login** via XDG autostart
+
+## Screenshots
+
+The tray icon shows your current usage with:
+- Arc fill = session usage (5-hour window)
+- Color = worst-case urgency (max of session/weekly)
+- Panel label = "45%|67%" format
+
+## Requirements
+
+- Linux with GNOME Shell (or compatible desktop with AppIndicator support)
+- Python 3.11+
+- [Claude Code CLI](https://claude.ai/code) installed and authenticated
+- AppIndicator extension for GNOME Shell
+
+### System Dependencies
+
+```bash
+# Ubuntu/Debian
+sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7
+
+# Fedora
+sudo dnf install python3-gobject python3-cairo libayatana-appindicator-gtk3 libnotify
+
+# Arch
+sudo pacman -S python-gobject python-cairo libayatana-appindicator libnotify
+```
+
+### GNOME Shell Extension
+
+Install the [AppIndicator Support](https://extensions.gnome.org/extension/615/appindicator-support/) extension for GNOME Shell to see system tray icons.
+
+## Installation
+
+### Quick Install (recommended)
+
+```bash
+git clone https://github.com/Maex-z9/CC_Usage.git
+cd CC_Usage
+./install.sh
+```
+
+This installs system dependencies and the app. Then run with: `claude-usage`
+
+### Manual Install
+
+1. Install system dependencies:
+   ```bash
+   # Ubuntu/Debian
+   sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1 gir1.2-notify-0.7
+
+   # Fedora
+   sudo dnf install python3-gobject python3-cairo libayatana-appindicator-gtk3 libnotify
+
+   # Arch
+   sudo pacman -S python-gobject python-cairo libayatana-appindicator libnotify
+   ```
+
+2. Install the app:
+   ```bash
+   pip install git+https://github.com/Maex-z9/CC_Usage.git
+   ```
+
+3. Authenticate with Claude Code (if not already done):
+   ```bash
+   claude
+   # Follow the authentication flow
+   ```
+
+## Usage
+
+Run the application:
+
+```bash
+claude-usage
+```
+
+Or if running from source:
+```bash
+python3 -m src.main
+```
+
+### Menu Options
+
+Click the tray icon to access:
+- Current usage percentages and reset time
+- **Refresh** - Force update usage data
+- **Settings** submenu:
+  - Pause Notifications - Temporarily disable alerts
+  - Autostart on Login - Enable/disable auto-start
+  - Edit Config File - Open config in text editor
+- **Quit** - Exit the application
+
+### Configuration
+
+Config file location: `~/.config/claude-usage-overlay/config.json`
+
+```json
+{
+  "session_thresholds": [50, 75, 90],
+  "weekly_thresholds": [50, 75, 90],
+  "polling_interval": 300,
+  "pause_notifications": false,
+  "autostart_enabled": false
+}
+```
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `session_thresholds` | Alert thresholds for 5-hour session usage | `[50, 75, 90]` |
+| `weekly_thresholds` | Alert thresholds for 7-day weekly usage | `[50, 75, 90]` |
+| `polling_interval` | Seconds between API checks (30-3600) | `300` (5 min) |
+| `pause_notifications` | Disable popup alerts | `false` |
+| `autostart_enabled` | Start on login | `false` |
+
+## How It Works
+
+1. Reads your OAuth token from `~/.claude/.credentials.json` (created by Claude Code CLI)
+2. Polls the Anthropic usage API every 5 minutes (configurable)
+3. Displays usage in the system tray with color-coded urgency
+4. Shows desktop notifications when thresholds are crossed
+
+## Privacy & Security
+
+- **No API keys stored in the repo** - Uses Claude Code's existing credentials
+- **Credentials stay local** - Reads from `~/.claude/.credentials.json`
+- **Config stays local** - Stored in `~/.config/claude-usage-overlay/`
+- **No data sent anywhere** - Only communicates with Anthropic's API
+
+## Known Issues
+
+See [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for details on:
+- GNOME Shell tooltip limitations (using panel label instead)
+- AppIndicator menu accelerator limitations
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+Built with [Claude Code](https://claude.ai/code) using the [GSD workflow](https://github.com/get-shit-done/gsd).

claude_code_usage-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+claude_code_usage-1.0.0.dist-info/licenses/LICENSE,sha256=alXcUJ2-k8eqG_Amt8y9Hhlb8fT1nABafZOqWDmdzUw,1060
+src/__init__.py,sha256=rzeXYIMbNbWPF6gpjv7luGXLZA67r_5GU5ZGUNb8pKA,27
+src/api.py,sha256=IChRjcU8vqmiQ64YOQRXiQi8DSNxvknD4Y4mVOwH01g,6100
+src/autostart.py,sha256=2Rnsr1y_yXbwwARnoYJl5_uQfMch8XsD7vgJi2CfTII,2399
+src/config.py,sha256=_PIPM7wfbQq1c7tHT26_L39PXbLVQWuzxaB2FMWiavw,5300
+src/icon_generator.py,sha256=Ljwhrj9ezqJSLspLu2DlmJGbfvcOLJnW50O-4J3gwKE,2861
+src/main.py,sha256=A7Ej5kqbtOYWUGSuZxx6bM-7WNimjjAs--04_kvvta0,506
+src/notifier.py,sha256=3j5ZmhaFMfv5XDLMCFaOgSCCw5jffn4N6dNz2R7gd8I,10267
+src/tray.py,sha256=sCvQLsNdm3uBtdeNGzFmLxzLT1h1w_LH4ZsajZIlg4I,10995
+src/utils.py,sha256=ZqGvw-oyzHompxRMUeYT5FdJFaQ6uvoAthhu-3bPGJk,893
+claude_code_usage-1.0.0.dist-info/METADATA,sha256=tbz_u_pwUI_L31RgUWMCvrIAmkIltnjCKUimCLhyUTA,5613
+claude_code_usage-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+claude_code_usage-1.0.0.dist-info/entry_points.txt,sha256=sRUb89gemjebLTvCQVv6TJWunjYrD-i_it3A3E9bJVc,95
+claude_code_usage-1.0.0.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+claude_code_usage-1.0.0.dist-info/RECORD,,

claude_code_usage-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

claude_code_usage-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+claude-usage = src.main:main
+
+[gui_scripts]
+claude-usage-gui = src.main:main

claude_code_usage-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max
+
+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_code_usage-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+src

src/__init__.py

@@ -0,0 +1 @@
+# overlay-CC-usage package

src/api.py

@@ -0,0 +1,202 @@
+"""API client for fetching Claude Code usage data."""
+
+import sys
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+import requests
+
+
+USAGE_ENDPOINT = "https://api.anthropic.com/api/oauth/usage"
+
+
+@dataclass
+class UsageData:
+    """Structured usage data from the Anthropic API."""
+
+    session_percent: float  # from five_hour.utilization
+    session_resets_at: Optional[datetime]  # from five_hour.resets_at
+    weekly_percent: float  # from seven_day.utilization
+    weekly_resets_at: Optional[datetime]  # from seven_day.resets_at
+
+
+class APIError(Exception):
+    """Base exception for API errors."""
+
+    pass
+
+
+class AuthenticationError(APIError):
+    """Exception for 401 authentication failures."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """Exception for 429 rate limit errors."""
+
+    def __init__(self, message: str, retry_after: int = 60):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+def fetch_usage(access_token: str) -> UsageData:
+    """Fetch usage data from the Anthropic API.
+
+    Args:
+        access_token: OAuth access token
+
+    Returns:
+        UsageData: Parsed usage information
+
+    Raises:
+        AuthenticationError: On 401 responses
+        RateLimitError: On 429 responses
+        APIError: On other errors
+    """
+    headers = {
+        "Authorization": f"Bearer {access_token}",
+        "Accept": "application/json",
+        "anthropic-beta": "oauth-2025-04-20",
+    }
+
+    try:
+        response = requests.get(USAGE_ENDPOINT, headers=headers, timeout=10)
+    except requests.RequestException as e:
+        raise APIError(f"Network error: {e}")
+
+    if response.status_code == 200:
+        try:
+            data = response.json()
+
+            # Parse five_hour data
+            five_hour = data.get("five_hour", {})
+            session_percent = five_hour.get("utilization", 0.0)
+            session_resets_str = five_hour.get("resets_at")
+            session_resets_at = (
+                datetime.fromisoformat(session_resets_str.replace("Z", "+00:00"))
+                if session_resets_str
+                else None
+            )
+
+            # Parse seven_day data
+            seven_day = data.get("seven_day", {})
+            weekly_percent = seven_day.get("utilization", 0.0)
+            weekly_resets_str = seven_day.get("resets_at")
+            weekly_resets_at = (
+                datetime.fromisoformat(weekly_resets_str.replace("Z", "+00:00"))
+                if weekly_resets_str
+                else None
+            )
+
+            return UsageData(
+                session_percent=session_percent,
+                session_resets_at=session_resets_at,
+                weekly_percent=weekly_percent,
+                weekly_resets_at=weekly_resets_at,
+            )
+        except (KeyError, ValueError, TypeError) as e:
+            raise APIError(f"Failed to parse API response: {e}")
+
+    elif response.status_code == 401:
+        raise AuthenticationError("OAuth token is invalid or expired")
+
+    elif response.status_code == 429:
+        retry_after = int(response.headers.get("Retry-After", 60))
+        raise RateLimitError(
+            f"Rate limited, retry after {retry_after} seconds", retry_after
+        )
+
+    elif 500 <= response.status_code < 600:
+        raise APIError(f"Server error: {response.status_code}")
+
+    else:
+        raise APIError(
+            f"Unexpected response: {response.status_code} - {response.text}"
+        )
+
+
+def fetch_with_retry(access_token: str, max_retries: int = 3) -> UsageData:
+    """Fetch usage data with retry logic.
+
+    Args:
+        access_token: OAuth access token
+        max_retries: Maximum number of retry attempts
+
+    Returns:
+        UsageData: Parsed usage information
+
+    Raises:
+        AuthenticationError: On 401 responses (no retry)
+        APIError: If all retries exhausted
+    """
+    last_exception = None
+
+    for attempt in range(max_retries):
+        try:
+            return fetch_usage(access_token)
+
+        except AuthenticationError:
+            # Don't retry authentication errors - user action needed
+            raise
+
+        except RateLimitError as e:
+            last_exception = e
+            if attempt < max_retries - 1:
+                print(
+                    f"Rate limited, waiting {e.retry_after}s before retry {attempt + 2}/{max_retries}...",
+                    file=sys.stderr,
+                )
+                time.sleep(e.retry_after)
+            else:
+                print(f"Rate limited, all retries exhausted", file=sys.stderr)
+
+        except APIError as e:
+            last_exception = e
+            if attempt < max_retries - 1:
+                # Exponential backoff with cap at 30 seconds
+                wait_time = min(30, 2**attempt)
+                print(
+                    f"API error: {e}. Retrying in {wait_time}s ({attempt + 2}/{max_retries})...",
+                    file=sys.stderr,
+                )
+                time.sleep(wait_time)
+            else:
+                print(f"API error, all retries exhausted: {e}", file=sys.stderr)
+
+    # All retries exhausted
+    if last_exception:
+        raise last_exception
+    else:
+        raise APIError("All retries exhausted")
+
+
+if __name__ == "__main__":
+    """Integration test: fetch and display current usage."""
+    from src.config import get_access_token
+
+    try:
+        # Get OAuth token
+        token = get_access_token()
+
+        # Fetch usage data
+        usage = fetch_with_retry(token)
+
+        # Display results
+        print("Claude Code Usage:")
+        print(f"  Session (5-hour): {usage.session_percent:.1f}% (resets at {usage.session_resets_at})")
+        print(f"  Weekly (7-day): {usage.weekly_percent:.1f}% (resets at {usage.weekly_resets_at})")
+
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    except AuthenticationError as e:
+        print(f"Authentication failed: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    except APIError as e:
+        print(f"API error: {e}", file=sys.stderr)
+        sys.exit(1)

src/autostart.py

@@ -0,0 +1,94 @@
+"""Autostart management for Claude Usage Overlay."""
+
+import os
+from pathlib import Path
+
+
+def get_autostart_path() -> Path:
+    """Get XDG-compliant autostart directory path.
+
+    Returns:
+        Path: Path to autostart directory
+    """
+    config_home = os.environ.get('XDG_CONFIG_HOME')
+    if config_home:
+        base = Path(config_home)
+    else:
+        base = Path.home() / '.config'
+
+    autostart_dir = base / 'autostart'
+    autostart_dir.mkdir(parents=True, exist_ok=True)
+
+    return autostart_dir
+
+
+def get_desktop_file_path() -> Path:
+    """Get path to the .desktop file.
+
+    Returns:
+        Path: Path to claude-usage-overlay.desktop
+    """
+    return get_autostart_path() / 'claude-usage-overlay.desktop'
+
+
+def create_autostart_entry(enable: bool = True):
+    """Create or update autostart .desktop file.
+
+    Args:
+        enable: If True, enable autostart. If False, disable (set Hidden=true).
+    """
+    desktop_file = get_desktop_file_path()
+
+    # Get absolute path to main.py
+    project_root = Path(__file__).parent.parent.absolute()
+    exec_path = f"/usr/bin/python3 {project_root}/src/main.py"
+
+    # Desktop entry content
+    hidden_value = "false" if enable else "true"
+    content = f"""[Desktop Entry]
+Type=Application
+Version=1.0
+Name=Claude Code Usage Monitor
+Comment=System tray monitor for Claude Code token usage
+Exec={exec_path}
+Icon=dialog-information
+Terminal=false
+Categories=Utility;Monitor;
+StartupNotify=false
+X-GNOME-Autostart-enabled=true
+Hidden={hidden_value}
+"""
+
+    # Write .desktop file
+    desktop_file.write_text(content)
+    desktop_file.chmod(0o755)
+
+
+def remove_autostart_entry():
+    """Remove autostart .desktop file."""
+    desktop_file = get_desktop_file_path()
+    if desktop_file.exists():
+        desktop_file.unlink()
+
+
+def is_autostart_enabled() -> bool:
+    """Check if autostart is enabled.
+
+    Returns:
+        bool: True if autostart is enabled (file exists and Hidden!=true)
+    """
+    desktop_file = get_desktop_file_path()
+
+    if not desktop_file.exists():
+        return False
+
+    content = desktop_file.read_text()
+
+    # Parse for Hidden= line (case insensitive value)
+    for line in content.splitlines():
+        if line.strip().startswith('Hidden='):
+            value = line.split('=', 1)[1].strip().lower()
+            return value != 'true'
+
+    # If Hidden not present, autostart is enabled
+    return True