Menu bar icon and detailed usage popover

What's New

• v3.0.3 (2026-03-10): 6-tier pace system (Comfortable → Runaway) with colored pace markers on progress bars, 3 color modes (Multi-Color/Greyscale/Single Color) for menu bar and statusline, label toggles (Ctx/Usage/Reset), 24-hour time format, terminal-matching preview colors, CPU spin-loop fix in menu bar rendering

• v3.0.2 (2026-03-10): API cost tracking with daily chart, browser-based authentication (WKWebView sign-in), rate limit header usage for CLI OAuth, auto-sizing popover, 3-way time display picker, adaptive green color, session key expiry tracking & notifications

• v3.0.1 (2026-03-08): Popover settings tab (remaining time toggle), multi-display CPU fix

• v3.0.0 - Major Release (2026-03-08):

  • Headless mode: Remote Desktop support for headless Mac environments
  • Usage history: Interactive timeline charts with export to JSON/CSV
  • Global keyboard shortcuts: Configurable hotkeys (no Accessibility permission needed)
  • Auto-switch profiles: Automatically switch when session limit reached
  • Borderless settings window: Full vibrancy design with custom traffic lights
  • 6 new statusline components: Model name, context window, profile name, and more
  • Time-elapsed markers & pace-aware coloring: Smart progress indicators
  • Network debug view: Timed capture with request/response detail viewer
  • Simplified Chinese (9th language)
  • 12 ported improvements from novastate fork including CLI auto-detection, wake-from-sleep refresh, and custom notification thresholds

• v2.3.0 – Multi-profile menu bar display, remaining percentage toggle

• v2.2.0 – Multi-profile management, CLI integration, Korean language

• v2.1.0 – 3-step setup wizard, smart organization preservation

• v2.0.0 – Apple code signing, automatic updates, Keychain security

View Full Release History

Getting Started

Prerequisites

Before installing Claude Usage Tracker, ensure you have:

• macOS 14.0 (Sonoma) or later - Check: Apple menu → About This Mac
• Active Claude AI account - Sign up at claude.ai

Authentication (choose one method):

• Easiest: Claude Code installed and logged in - App automatically uses CLI credentials (v2.2.2+)
• Browser Sign-In: Sign in via the built-in browser — session key extracted automatically (v3.0.2+)
• Manual: Web browser access to extract session key from claude.ai (Chrome, Safari, Firefox, etc.)

Note: For terminal statusline integration, you'll still need to manually configure a session key even if using Claude Code OAuth

Installation

Option 1: Homebrew (Recommended)

brew install --cask hamed-elfayome/claude-usage/claude-usage-tracker

Or tap first, then install:

brew tap hamed-elfayome/claude-usage
brew install --cask claude-usage-tracker

Note: Starting with v2.0.0, the app is officially signed with an Apple Developer certificate. No security workarounds needed!

To update:

brew upgrade --cask claude-usage-tracker

Or use the built-in automatic update feature (Settings → Updates).

To uninstall:

brew uninstall --cask claude-usage-tracker

Option 2: Direct Download

Download Claude-Usage.zip

1. Download the .zip file from the link above
2. Extract the zip file (double-click or use Archive Utility)
3. Drag Claude Usage.app to your Applications folder
4. Double-click to launch - that's it!

v2.0.0+ Note: The app is now officially signed with an Apple Developer certificate. You can install and run it like any other Mac application - no security warnings or workarounds needed.

Automatic Updates: Once installed, the app will automatically check for updates and notify you when new versions are available (Settings → Updates).

Option 3: Build from Source

# Clone the repository
git clone https://github.com/hamed-elfayome/Claude-Usage-Tracker.git
cd Claude-Usage-Tracker

# Open in Xcode
open "Claude Usage.xcodeproj"

# Build and run (⌘R)

Quick Start Guide

Option A: Automatic Setup with Claude Code (Easiest)

New in v2.2.2: If you have Claude Code installed and logged in, the app works automatically!

1. Install Claude Code (if not already installed)

   • Download from claude.com/claude-code
   • Log in using claude login

2. Launch Claude Usage Tracker

   • The app automatically detects your Claude Code Account
   • No manual configuration needed!

3. Verify It's Working

   • Click the menu bar icon
   • You should see your usage statistics immediately

Option B: Browser Sign-In (v3.0.2+)

If you don't use Claude Code, sign in directly through the app:

1. Click the menu bar icon and select "Settings"
2. Navigate to "Personal Usage" tab
3. Click "Sign in to Claude.ai" — an embedded browser opens
4. Log in with your Claude.ai credentials (email, Google SSO, etc.)
5. Session key is extracted automatically — the app validates and saves it
6. Select your organization from the list and confirm

Option C: Manual Setup with Session Key

If you prefer manual configuration:

Step 1: Extract Your Session Key

1. Open Claude AI

   • Navigate to claude.ai in your browser
   • Make sure you're logged in

2. Open Developer Tools

   • Chrome/Edge: Press F12 or Cmd+Option+I (macOS) / Ctrl+Shift+I (Windows)
   • Safari: Enable Developer menu in Preferences → Advanced, then press Cmd+Option+I
   • Firefox: Press F12 or Cmd+Option+I (macOS) / Ctrl+Shift+I (Windows)

3. Navigate to Cookies

   • Go to: Application tab (Chrome/Edge) or Storage tab (Firefox)
   • Expand: Cookies → https://claude.ai
   • Find: sessionKey cookie
   • Copy: The value (starts with sk-ant-sid01-...)

Step 2: Configure Session Key

1. Click the menu bar icon and select "Settings"
2. Navigate to "Personal Usage" tab
3. Expand "Advanced: Manual Session Key"
4. Paste your session key and click "Test Connection"
5. Select your organization from the list
6. Review and click "Save Configuration"

Step 3: Verify It's Working

1. Check Menu Bar: You should see the Claude Usage icon in your menu bar
2. Click the Icon: Popover appears showing your usage statistics
3. View Data: Session usage, weekly usage, and reset timers should display

Success! The app is now monitoring your Claude usage.

Next Steps

• Customize Icon: Go to Settings → Appearance to choose your preferred menu bar style