A lightweight cross-platform system tray application for monitoring your Claude Code API usage in real-time. Available for Linux, macOS, and Windows.
- System tray indicator - Color-coded icon shows usage status at a glance
- Green: Normal usage (< 75%)
- Yellow: Warning (>= 75% and < 90%)
- Red: Critical (>= 90%)
- Detailed menu - Shows 5-hour, 7-day, Opus, and Sonnet usage with reset times
- Notifications - Alerts at 75% and 90% thresholds
- Auto-refresh - Polls API every 2 minutes (with jitter)
- Manual refresh - Click "↻ Refresh" anytime
- Autostart - Optionally launch on system boot
- Cross-platform - Native builds for Linux, macOS, and Windows
| High Usage | Low Usage |
|---|---|
 |
 |
The tray menu displays usage for each time window with visual progress bars, color-coded status indicators, and time until reset.
- Claude Code authenticated:
claude auth login
- Rust 1.77.2+ with Cargo
- Tauri CLI:
cargo install tauri-cli - Platform-specific dependencies: See platform sections below
Download the latest release for your platform from the Releases page.
# Install the package
sudo dpkg -i claude-usage-tracker_0.1.0_amd64.deb
# If dependencies are missing, fix them with:
sudo apt-get install -fThe package includes all required dependencies and installs:
- Application binary to
/usr/bin/ - Desktop entry and icon
- XDG autostart entry (disabled by default)
The .AppImage is a portable package that works on most Linux distributions:
# Make executable
chmod +x Claude-Usage-Tracker_0.1.0_amd64.AppImage
# Run directly
./Claude-Usage-Tracker_0.1.0_amd64.AppImage# Ubuntu/Debian
sudo apt install libwebkit2gtk-4.1-dev libayatana-appindicator3-dev
# Fedora
sudo dnf install webkit2gtk4.1-devel libappindicator-gtk3-devel
# Arch
sudo pacman -S webkit2gtk-4.1 libayatana-appindicator- Download
Claude-Usage-Tracker_0.1.0_universal.dmg - Open the DMG file
- Drag the app to your Applications folder
- Launch from Applications or Spotlight
The universal binary runs natively on both Intel and Apple Silicon Macs.
# Not yet available
brew install --cask claude-usage-tracker- Download
Claude-Usage-Tracker_0.1.0_x64_en-US.msi - Run the installer
- Follow the installation wizard
- Launch from Start Menu
- Download
Claude-Usage-Tracker_0.1.0_x64-setup.exe - Run the setup executable
- Follow the prompts
# Clone and build
git clone <repository-url>
cd claude-usage
cargo tauri build
# Binary will be in target/release/bundle/cargo tauri devThe application can automatically start when you log into your system.
Enabling/disabling:
- Click the tray icon menu
- Select "Start on login" (shows checkmark when enabled)
Uses the XDG Autostart standard. Entry created at:
~/.config/autostart/com.claude-usage-tracker.desktop
Uses Launch Services. Entry managed via System Preferences > Users & Groups > Login Items.
Uses the Windows Registry (HKCU\Software\Microsoft\Windows\CurrentVersion\Run).
-
Ensure you're authenticated with Claude Code:
claude auth login
-
Launch the app - it will appear in your system tray
-
Click the tray icon to see:
- 5-hour usage and reset time
- 7-day usage and reset time
- Last update timestamp
- Refresh and Quit options
The app uses credentials from ~/.claude/.credentials.json (created by claude auth login).
| Platform | Path |
|---|---|
| Linux | ~/.config/claude-usage-tracker/config.toml |
| macOS | ~/Library/Application Support/com.claude-usage-tracker/config.toml |
| Windows | %APPDATA%\com.claude-usage-tracker\config.toml |
If the config file doesn't exist, the app creates one with sensible defaults on first run.
# Thresholds (apply uniformly to all usage windows)
warning-threshold = 75.0 # Warning notification threshold (%)
critical-threshold = 90.0 # Critical notification threshold (%)
reset-threshold = 50.0 # Reset notification state when below (%)
# Intervals
polling-interval-minutes = 2 # API poll interval (default: 2 min)
notification-cooldown-minutes = 5 # Minimum time between notificationsThe tray icon shows both windows: left half = 5-hour, right half = 7-day.
- Green: Normal (< warning threshold)
- Yellow: Warning (>= warning and < critical)
- Red: Critical (>= critical threshold)
Default: 2 minutes with fixed ±30-second jitter (minimum 60s between polls). Jitter is not configurable.
Run claude auth login to authenticate with Claude Code.
Re-run claude auth login when prompted to refresh your credentials.
Ensure you have a system tray compatible with AppIndicator:
- GNOME: Install the AppIndicator extension
- KDE/XFCE: Should work out of the box
Install system dependencies (see Build dependencies (Linux) above).
Right-click the app and select "Open", then confirm in the dialog. This is only required once.
The app appears in the menu bar (top-right of screen). If not visible, check System Preferences > Control Center > Menu Bar Only.
Click "More info" then "Run anyway". This occurs because the app is not code-signed.
Check the system tray overflow area (click the ^ arrow in the taskbar). You can drag the icon to the visible area.
src/
├── main.rs # App entry, thin wiring layer
├── lib.rs # Module declarations, AppState, event handler loop
├── events.rs # AppEvent, CredentialRefreshResult
├── service.rs # Polling loop, notifications, credential refresh
├── auth.rs # Credential loading from ~/.claude/
├── api.rs # Claude API client with retry logic
├── tray.rs # System tray UI, menu handling
└── config.rs # Configuration loading and validation
icons/ # Tray icon variants (project root)
MIT