Skip to content

README.md

Latest commit

 

History

History
182 lines (132 loc) · 6.27 KB

README.md

File metadata and controls

182 lines (132 loc) · 6.27 KB
Raw

Claude Code Usage Monitor

Built with Claude Code

A lightweight desktop utility for macOS and Linux that displays your Claude Code usage limits in the system tray and a dashboard window.

System tray icon    Dashboard window

Features

  • System tray icon showing your current 5-hour usage percentage as a color-coded ring (green/yellow/red)
  • Right-click menu with all usage stats and reset times at a glance
  • Dashboard window with progress bars, reset countdowns, daily activity charts, and usage insights
  • Configurable alerts — set a custom 5h usage threshold (default 70%) to get notified before hitting limits
  • Reset notifications — opt-in alerts when your usage window resets
  • Extra usage tracking for overage credits (if enabled on your plan)
  • Polls the Anthropic usage API every 60 seconds with manual refresh option
  • Stores usage history locally in SQLite for trend tracking

Requirements

  • Python 3.11+
  • macOS or Linux
  • An active Claude Code login (the app reads your existing credentials)

Installation

git clone https://github.com/raviboth/ccusage.git
cd ccusage
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Auto-Start on Login

macOS:

./scripts/install-macos.sh

Linux:

./scripts/install-linux.sh

To uninstall, run the corresponding uninstall-macos.sh or uninstall-linux.sh.

Standalone .app (macOS)

Build a double-clickable app bundle that doesn't require Python:

pip install pyinstaller
./scripts/build-macos.sh

The built app will be at dist/Claude Code Usage Monitor.app. Copy it to /Applications/ to install.

Standalone AppImage (Linux)

Build a portable AppImage that doesn't require Python:

pip install pyinstaller
./scripts/build-linux.sh

The built AppImage will be at dist/ccusage-x86_64.AppImage. Make it executable and run:

chmod +x dist/ccusage-x86_64.AppImage
./dist/ccusage-x86_64.AppImage

Pre-built Binaries

Pre-built macOS .app and Linux .AppImage binaries are available on the Releases page.

macOS note: Downloaded .app bundles are quarantined by Gatekeeper since they aren't signed with an Apple Developer certificate. Remove the quarantine flag before first launch:

xattr -cr "Claude Code Usage Monitor.app"

Usage

Manual Start

source .venv/bin/activate
python -m src.main

Using the CLI Wrapper

./scripts/claude-monitor start    # Start in background
./scripts/claude-monitor stop     # Stop
./scripts/claude-monitor status   # Check if running

The app will appear in your system tray. Right-click the icon to see usage stats or open the dashboard.

Tray Icon

The tray icon displays the current 5h usage percentage inside a color-coded ring:

Color Meaning
Green 0-59% usage
Yellow 60-79% usage
Red 80%+ usage

Dashboard

The dashboard shows:

  • 5-Hour Limit — rolling usage with reset countdown
  • 7-Day Limit — weekly usage with reset countdown
  • Extra Usage — overage credits used vs. monthly cap (if enabled)
  • Alerts — configurable threshold for 5h usage notifications (spinbox, 10-100%) and toggle for reset notifications
  • Daily Activity — bar chart of messages, sessions, or tool calls over the last 30 days
  • Insights — peak hours, most active day, models used, total sessions

How It Works

The app reads your Claude Code OAuth token from the system credential store (macOS Keychain or Linux secret-tool) and polls the Anthropic usage API. No API keys or tokens are stored by this app — credentials are read fresh from the keychain on each request.

Local usage history from ~/.claude/stats-cache.json is used for the activity chart and insights.

Security

  • No credentials stored — OAuth tokens are read from the system keychain at runtime and held in memory only for the duration of each API call
  • No logging of sensitive data — authorization headers are never printed, logged, or written to disk
  • Restricted file permissions — SQLite database is created with 0600 permissions in the platform app data directory
  • Parameterized SQL — all database queries use parameterized statements
  • HTTPS only — all API communication uses TLS

Data is stored locally in:

  • macOS: ~/Library/Application Support/ccusage/
  • Linux: ~/.local/share/ccusage/

Project Structure

src/
├── main.py            # Entry point, wires everything together
├── auth.py            # Token retrieval from system keychain
├── api.py             # Usage API polling
├── db.py              # SQLite storage for usage history
├── local_stats.py     # Reads ~/.claude/stats-cache.json
├── notifications.py   # Threshold and reset alert notifications
├── tray.py            # System tray icon and menu (QSystemTrayIcon)
├── dashboard.py       # Main PyQt6 window with progress bars
├── charts.py          # Daily activity chart and insights panel
├── icons.py           # Dynamic tray icon rendering with Pillow
├── utils.py           # Shared formatting and color utilities
└── constants.py       # Configuration values

scripts/
├── claude-monitor       # CLI wrapper (start/stop/status)
├── build-macos.sh       # Build standalone .app bundle
├── install-macos.sh     # macOS launch agent installer
├── uninstall-macos.sh   # macOS launch agent uninstaller
├── install-linux.sh     # Linux systemd service installer
└── uninstall-linux.sh   # Linux systemd service uninstaller

Known Limitations

  • The usage API endpoint is internal and undocumented — Anthropic could change it at any time. The app degrades gracefully if the endpoint is unavailable.
  • The OAuth token is managed by Claude Code. If you're not logged in, the app will show a "not authenticated" message.
  • On macOS with a notch, the tray icon may be hidden if the menu bar is crowded. Hold Cmd and drag other icons to make room.

License

MIT