claude-usage/README.md at master · utajum/claude-usage

Linux System Tray

Windows System Tray

                                                   
  ░█▀▀░█░░░█▀█░█░█░█▀▄░█▀▀░░░█░█░█▀▀░█▀█░█▀▀░█▀▀
  ░█░░░█░░░█▀█░█░█░█░█░█▀▀░░░█░█░▀▀█░█▀█░█░█░█▀▀
  ░▀▀▀░▀▀▀░▀░▀░▀▀▀░▀▀░░▀▀▀░░░▀▀▀░▀▀▀░▀░▀░▀▀▀░▀▀▀
          ╔═══════════════════════════════╗
          ║  SYSTEM TRAY USAGE MONITOR    ║
          ╚═══════════════════════════════╝

> ESTABLISHING NEURAL UPLINK TO ANTHROPIC SERVERS...

> CONNECTION SECURED :: MONITORING ACTIVE

🔥 Watch your tokens burn in real-time. Your wallet weeps silently. 🔥

Project Page: https://claude-usage.elevatech.xyz

`░▒▓█ 0x00 :: SYSTEM OVERVIEW █▓▒░`

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   Claude Usage is a system tray application that monitors your             │
│   Claude Code API consumption. Tracks token burn rate across models.       │
│                                                                             │
│   > No browser required                                                     │
│   > Real-time progress bars                                                 │
│   > Multi-model breakdown (Opus, Sonnet)                                    │
│   > Reset countdown timers                                                  │
│   > Works on Linux, Windows, macOS                                          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

`░▒▓█ 0x01 :: PLATFORM COMPATIBILITY MATRIX █▓▒░`

> SCANNING TARGET ARCHITECTURES...
> [OK] COMPATIBILITY CHECK COMPLETE

PLATFORM	ARCH	STATUS	PACKAGE
Windows	x64	`[SUPPORTED]`	`claude-usage-windows-amd64.zip`
macOS	Universal	`[SUPPORTED]`	`Claude-Usage-*.dmg`
macOS	Intel	`[SUPPORTED]`	`claude-usage-darwin-amd64`
macOS	Apple Silicon	`[SUPPORTED]`	`claude-usage-darwin-arm64`
Linux	x64	`[SUPPORTED]`	`claude-usage-linux-amd64`
Linux	ARM64	`[SUPPORTED]`	`claude-usage-linux-arm64`

> DESKTOP ENVIRONMENT SCAN:
  ├─ [OK] KDE Plasma
  ├─ [OK] GNOME (requires AppIndicator extension)
  ├─ [OK] XFCE
  ├─ [OK] Cinnamon
  ├─ [OK] MATE
  ├─ [OK] Budgie
  └─ [OK] Any DE supporting StatusNotifierItem

`░▒▓█ 0x02 :: DEPLOYMENT PROTOCOLS █▓▒░`

╔══════════════════════════════════════════════════════════════════════════════╗
║  > BINARY PACKAGES AVAILABLE AT:                                             ║
╚══════════════════════════════════════════════════════════════════════════════╝

https://github.com/utajum/claude-usage/releases

Windows `> TARGET: WINDOWS_x64`

1. Download claude-usage-windows-amd64.zip from releases
2. Extract the ZIP file
3. Right-click install-windows.ps1 → "Run with PowerShell"
4. Find "Claude Usage" in Start Menu

Manual Installation:

# Or run from PowerShell directly:
powershell -ExecutionPolicy Bypass -File install-windows.ps1

# To uninstall:
powershell -ExecutionPolicy Bypass -File install-windows.ps1 -Uninstall

What gets installed:

%LOCALAPPDATA%\Programs\claude-usage\claude-usage.exe
Start Menu shortcut
Startup shortcut (autostart on login)

macOS `> TARGET: MACOS (Universal)`

# Option 1: Download DMG (recommended)
1. Download Claude-Usage-*.dmg from releases
2. Open the DMG file
3. Drag "Claude Usage" to Applications folder
4. Right-click → Open (first time only, to bypass Gatekeeper)

# Option 2: Command line install
curl -sL https://github.com/utajum/claude-usage/releases/latest/download/claude-usage-darwin-arm64 -o claude-usage
chmod +x claude-usage
./claude-usage

Enable autostart:

# Copy the LaunchAgent plist (from source repo)
cp assets/macos/com.github.utajum.claude-usage.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.github.utajum.claude-usage.plist

Linux `> TARGET: LINUX (x64/ARM64)`

One-liner install (recommended):

curl -sL https://raw.githubusercontent.com/utajum/claude-usage/master/scripts/install-linux.sh | bash

This automatically:

Detects your architecture (x64 or ARM64)
Downloads the latest release
Installs to ~/.local/bin/
Creates desktop entry (shows in applications menu)
Enables autostart on login

Install options:

# Install without autostart
curl -sL https://raw.githubusercontent.com/utajum/claude-usage/master/scripts/install-linux.sh | bash -s -- --no-autostart

# Install without desktop entry
curl -sL https://raw.githubusercontent.com/utajum/claude-usage/master/scripts/install-linux.sh | bash -s -- --no-desktop

# Uninstall
curl -sL https://raw.githubusercontent.com/utajum/claude-usage/master/scripts/install-linux.sh | bash -s -- --uninstall

Manual download:

# x64
curl -sL https://github.com/utajum/claude-usage/releases/latest/download/claude-usage-linux-amd64 -o claude-usage

# ARM64
curl -sL https://github.com/utajum/claude-usage/releases/latest/download/claude-usage-linux-arm64 -o claude-usage

chmod +x claude-usage
./claude-usage

Build from source:

git clone https://github.com/utajum/claude-usage
cd claude-usage
make install-linux    # Full install with desktop integration
# or
make install          # Binary only

OpenCode Support:

Claude Usage also supports OpenCode credentials on Linux:

Right-click the tray icon and click "Source: Claude Code" to toggle to OpenCode
Credentials are read from ~/.local/share/opencode/auth.json
The app auto-detects available sources on first run
If only OpenCode credentials exist, it will be used by default

`░▒▓█ 0x03 :: NEURAL INTERFACE █▓▒░`

> HOVER OVER TRAY ICON TO ACCESS TELEMETRY FEED

Tooltip displays real-time consumption data:

┌────────────────────────────────────┐
│ CLAUDE USAGE                       │
│ Plan: Pro (5x)                     │
│ STATUS: THROTTLED                  │
│ ▕████████░░▏  80% 2h 15m ◀         │
│ ▕██████░░░░▏  60% 3d 5h            │
└────────────────────────────────────┘

LEGEND:
├─ First bar  :: 5-hour rolling window
├─ Second bar :: Weekly allocation
├─ ◀ marker   :: Active rate limiter
└─ Time       :: Reset countdown

`░▒▓█ 0x04 :: DATA STREAM SOURCES █▓▒░`

> SCANNING LOCAL FILESYSTEM FOR CLAUDE CREDENTIALS...

The app reads your Claude Code credentials to fetch real-time rate limit data from the API:

OS	CREDENTIALS FILE
Linux	`~/.claude/.credentials.json`
macOS	`~/.claude/.credentials.json`
Windows	`C:\Users\<username>\.claude\.credentials.json`

> DATA FLOW:
  ├─ [1] Read OAuth token from .credentials.json
  ├─ [2] Call Anthropic API for real-time rate limits
  └─ [3] Display usage % and reset timers

> PREREQUISITES:
  ├─ [REQUIRED] Claude Code CLI installed and logged in
  └─ [REQUIRED] Valid credentials file with OAuth token

Note: The stats-cache.json file is only used as a fallback when API data is unavailable.

`░▒▓█ 0x05 :: COMPILE FROM SOURCE █▓▒░`

> INITIATING BUILD SEQUENCE...

# Clone repository
git clone https://github.com/utajum/claude-usage
cd claude-usage

# Build for current platform
make build

# Or cross-compile for all targets
make build-all

# Generate icon assets
make generate-icons

# Platform-specific packaging
make build-macos-app  # Creates .app bundle (macOS only)

`> BUILD REQUIREMENTS`

┌─────────────────────────────────────────────────────────────────────────────┐
│  DEPENDENCY          VERSION        STATUS                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│  Go                  1.22+          [REQUIRED]                              │
│  CGO                 enabled        [REQUIRED for macOS/Windows]            │
│  UPX                 4.0+           [REQUIRED for optimized builds]         │
│  External libs       none           [PURE GO BUILD on Linux]                │
└─────────────────────────────────────────────────────────────────────────────┘

`░▒▓█ 0x06 :: SYSTEM CONFIGURATION █▓▒░`

> LOADING CONFIG PARAMETERS...

Config file locations:

OS	CONFIG_PATH
Linux	`~/.config/claude-usage/config.json`
macOS	`~/Library/Application Support/claude-usage/config.json`
Windows	`%APPDATA%\claude-usage\config.json`

{
  "refresh_interval_seconds": 300
}

> DEFAULT REFRESH RATE: 300 seconds (5 minutes)

`░▒▓█ 0x07 :: PERSISTENCE PROTOCOLS █▓▒░`

Linux `> AUTOSTART`

make autostart          # Enable persistence
make autostart-remove   # Disable persistence

Windows `> AUTOSTART`

The installer automatically creates a Startup shortcut. To manage manually:

Location: %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\Claude Usage.lnk

macOS `> AUTOSTART`

# Enable
launchctl load ~/Library/LaunchAgents/com.github.utajum.claude-usage.plist

# Disable  
launchctl unload ~/Library/LaunchAgents/com.github.utajum.claude-usage.plist

Or via System Settings → General → Login Items

`░▒▓█ 0x08 :: CORE LOGIC FLOW █▓▒░`

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   [1] READ    ──► Parse ~/.claude/stats-cache.json                          │
│                                                                             │
│   [2] PROCESS ──► Calculate token consumption per model                     │
│                                                                             │
│   [3] COMPUTE ──► Aggregate weekly totals (Monday-Sunday cycle)             │
│                                                                             │
│   [4] RENDER  ──► Generate dynamic tray icon based on usage %               │
│                                                                             │
│   [5] DISPLAY ──► System tray with hover tooltip                            │
│                                                                             │
│   [6] LOOP    ──► Auto-refresh every 5 minutes                              │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

`░▒▓█ 0x09 :: DIAGNOSTICS █▓▒░`

`> ERROR: ICON_NOT_VISIBLE`

LINUX:
├─ Verify DE supports StatusNotifierItem
├─ GNOME: Install AppIndicator extension
└─ Check system tray is enabled

WINDOWS:
├─ Check system tray overflow area (click ^ arrow)
├─ Right-click taskbar → Taskbar settings → System tray icons
└─ Enable "Claude Usage" to always show

MACOS:
├─ Check menu bar (may be hidden by notch on newer Macs)
└─ Try Bartender or similar app to manage menu bar items

ALL PLATFORMS:
└─ Confirm Claude Code is installed and operational

`> ERROR: NO_DATA_AVAILABLE`

├─ Execute 'claude' command at least once
├─ Verify ~/.claude/stats-cache.json exists
└─ Check file permissions

`░▒▓█ 0x0A :: MAKE TARGETS █▓▒░`

make help  # Show all available targets

Development:
  make build          - Build optimized (stripped + UPX, ~5MB)
  make build-fast     - Build stripped only, no UPX (~7.5MB)
  make build-debug    - Build with debug symbols (~12MB)
  make run            - Build and run
  make test           - Run tests
  make generate-icons - Generate icon assets

Installation (Linux):
  make install        - Install binary to ~/.local/bin
  make install-linux  - Full install (binary + desktop + autostart)
  make desktop-install- Install desktop entry (app menu)
  make autostart      - Enable autostart on login
  make uninstall      - Remove everything

Installation (macOS):
  make install-macos  - Install .app bundle + autostart
  make uninstall-macos- Remove app and autostart

Cross-compilation:
  make build-linux    - Build for Linux (amd64, arm64)
  make build-windows  - Build for Windows (amd64)
  make build-macos    - Build for macOS (Intel, Apple Silicon)
  make build-macos-app- Build macOS .app bundle
  make build-all      - Build for all platforms

`░▒▓█ 0x0B :: SUPPORT THE GRID █▓▒░`

> INITIATING DONATION PROTOCOL...
> CAFFEINE LEVELS: CRITICALLY LOW

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   If this tool saved you from rate limit anxiety, consider fueling         │
│   the development with some caffeinated tokens.                             │
│                                                                             │
│   > Every coffee = More features                                            │
│   > Every coffee = Faster bug fixes                                         │
│   > Every coffee = Developer happiness++                                    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

`░▒▓█ 0x0C :: LICENSE █▓▒░`

MIT License

Permission granted to copy, modify, distribute.
No warranty. Use at your own risk.

╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║   ░▒▓█ CONNECTION TERMINATED :: END OF TRANSMISSION █▓▒░                     ║
║                                                                              ║
║   > Stay connected to the grid                                               ║
║   > Monitor your burn rate                                                   ║
║   > Trust no one. Especially your token consumption.                         ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝

Project Page: https://claude-usage.elevatech.xyz

> SESSION_END :: 0x00000000

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`░▒▓█ 0x00 :: SYSTEM OVERVIEW █▓▒░`

`░▒▓█ 0x01 :: PLATFORM COMPATIBILITY MATRIX █▓▒░`

`░▒▓█ 0x02 :: DEPLOYMENT PROTOCOLS █▓▒░`

Windows `> TARGET: WINDOWS_x64`

macOS `> TARGET: MACOS (Universal)`

Linux `> TARGET: LINUX (x64/ARM64)`

`░▒▓█ 0x03 :: NEURAL INTERFACE █▓▒░`

`░▒▓█ 0x04 :: DATA STREAM SOURCES █▓▒░`

`░▒▓█ 0x05 :: COMPILE FROM SOURCE █▓▒░`

`> BUILD REQUIREMENTS`

`░▒▓█ 0x06 :: SYSTEM CONFIGURATION █▓▒░`

`░▒▓█ 0x07 :: PERSISTENCE PROTOCOLS █▓▒░`

Linux `> AUTOSTART`

Windows `> AUTOSTART`

macOS `> AUTOSTART`

`░▒▓█ 0x08 :: CORE LOGIC FLOW █▓▒░`

`░▒▓█ 0x09 :: DIAGNOSTICS █▓▒░`

`> ERROR: ICON_NOT_VISIBLE`

`> ERROR: NO_DATA_AVAILABLE`

`░▒▓█ 0x0A :: MAKE TARGETS █▓▒░`

`░▒▓█ 0x0B :: SUPPORT THE GRID █▓▒░`

`░▒▓█ 0x0C :: LICENSE █▓▒░`

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

░▒▓█ 0x00 :: SYSTEM OVERVIEW █▓▒░

░▒▓█ 0x01 :: PLATFORM COMPATIBILITY MATRIX █▓▒░

░▒▓█ 0x02 :: DEPLOYMENT PROTOCOLS █▓▒░

Windows > TARGET: WINDOWS_x64

macOS > TARGET: MACOS (Universal)

Linux > TARGET: LINUX (x64/ARM64)

░▒▓█ 0x03 :: NEURAL INTERFACE █▓▒░

░▒▓█ 0x04 :: DATA STREAM SOURCES █▓▒░

░▒▓█ 0x05 :: COMPILE FROM SOURCE █▓▒░

> BUILD REQUIREMENTS

░▒▓█ 0x06 :: SYSTEM CONFIGURATION █▓▒░

░▒▓█ 0x07 :: PERSISTENCE PROTOCOLS █▓▒░

Linux > AUTOSTART

Windows > AUTOSTART

macOS > AUTOSTART

░▒▓█ 0x08 :: CORE LOGIC FLOW █▓▒░

░▒▓█ 0x09 :: DIAGNOSTICS █▓▒░

> ERROR: ICON_NOT_VISIBLE

> ERROR: NO_DATA_AVAILABLE

░▒▓█ 0x0A :: MAKE TARGETS █▓▒░

░▒▓█ 0x0B :: SUPPORT THE GRID █▓▒░

░▒▓█ 0x0C :: LICENSE █▓▒░

`░▒▓█ 0x00 :: SYSTEM OVERVIEW █▓▒░`

`░▒▓█ 0x01 :: PLATFORM COMPATIBILITY MATRIX █▓▒░`

`░▒▓█ 0x02 :: DEPLOYMENT PROTOCOLS █▓▒░`

Windows `> TARGET: WINDOWS_x64`

macOS `> TARGET: MACOS (Universal)`

Linux `> TARGET: LINUX (x64/ARM64)`

`░▒▓█ 0x03 :: NEURAL INTERFACE █▓▒░`

`░▒▓█ 0x04 :: DATA STREAM SOURCES █▓▒░`

`░▒▓█ 0x05 :: COMPILE FROM SOURCE █▓▒░`

`> BUILD REQUIREMENTS`

`░▒▓█ 0x06 :: SYSTEM CONFIGURATION █▓▒░`

`░▒▓█ 0x07 :: PERSISTENCE PROTOCOLS █▓▒░`

Linux `> AUTOSTART`

Windows `> AUTOSTART`

macOS `> AUTOSTART`

`░▒▓█ 0x08 :: CORE LOGIC FLOW █▓▒░`

`░▒▓█ 0x09 :: DIAGNOSTICS █▓▒░`

`> ERROR: ICON_NOT_VISIBLE`

`> ERROR: NO_DATA_AVAILABLE`

`░▒▓█ 0x0A :: MAKE TARGETS █▓▒░`

`░▒▓█ 0x0B :: SUPPORT THE GRID █▓▒░`

`░▒▓█ 0x0C :: LICENSE █▓▒░`