Claude Usage Tracker is a lightweight, native macOS menu bar application that provides real-time monitoring of your Claude AI usage limits. Built entirely with Swift and SwiftUI, it offers a clean, intuitive interface to track your 5-hour session window, weekly usage limits, and Opus-specific consumption.
Key Capabilities
Multi-Profile Support: Manage unlimited Claude accounts with isolated credentials and settings
Multi-Profile Display: Monitor all profiles simultaneously in the menu bar
Claude Code Integration: Sync CLI accounts and auto-switch credentials when changing profiles
Real-Time Monitoring: Track session, weekly, API console usage, and API costs per profile
Usage History: Interactive charts tracking session, weekly, and billing data over time
Global Shortcuts: System-wide keyboard shortcuts (no Accessibility permission)
Headless Mode: Works on headless Macs via Remote Desktop
Developer Tools: Terminal statusline integration with model, context, profile display, weekly/extra usage segments, pace markers, per-element colors, and color modes
Privacy-First: Local storage, minimal anonymous analytics (version-only heartbeat), no cloud sync
Native Performance: Lightweight Swift/SwiftUI design for macOS
Menu bar icon and detailed usage popover
Live terminal statusline showing directory, branch, model, context, and color-coded usage
What's New
v3.1.0 (2026-04-14): Peak hours indicator with flame icon and countdown popover, right-click context menu on menu bar icons, per-element statusline color customization (#208), weekly & extra usage segments in statusline (#177), active profile indicator in multi-profile mode, Nix installation option (#211), 3 new languages (Brazilian Portuguese, Turkish, Ukrainian) bringing total to 12, 13 bug fixes including popover crash on profile switch, app hang on launch, and E3000 unauthorized errors
v3.0.3 (2026-03-10): 6-tier pace system with colored pace markers, 3 color modes (Multi-Color/Greyscale/Single Color), label toggles, 24-hour time format, terminal-matching preview colors
v3.0.2 (2026-03-10): API cost tracking with daily chart, browser-based authentication, rate limit header usage for CLI OAuth, auto-sizing popover, session key expiry tracking
v3.0.1 (2026-03-08): Popover settings tab, multi-display CPU fix
v3.0.0 - Major Release (2026-03-08): Headless mode, usage history charts, global shortcuts, auto-switch profiles, borderless settings, 6 new statusline components, Simplified Chinese
v2.3.0 – Multi-profile menu bar display, remaining percentage toggle
v2.2.0 – Multi-profile management, CLI integration, Korean language
v2.0.0 – Apple code signing, automatic updates, Keychain security
Extract the zip file (double-click or use Archive Utility)
Drag Claude Usage.app to your Applications folder
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 4: Build from Source
hljs language-bash
# 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!
Terminal Integration: Settings → Claude Code to set up statusline (requires session key configuration)
Keyboard Shortcuts: Settings → Shortcuts to configure global hotkeys
Advanced Configuration
Manual Session Key Setup
If you prefer to configure the session key manually instead of using the setup wizard:
hljs language-bash
# Create session key fileecho"sk-ant-sid01-YOUR_SESSION_KEY_HERE" > ~/.claude-session-key
# Set secure permissions (important for security)chmod 600 ~/.claude-session-key
After creating the file, launch the app and it will automatically detect the session key.
Multi-Profile Management
New in v2.2.0: Claude Usage Tracker now supports unlimited profiles, allowing you to manage multiple Claude accounts seamlessly with automatic credential switching.
New in v3.0.0: Auto-switch profiles when session limit reached, usage history tracking, and global keyboard shortcuts!
Features
Profile Management
Unlimited Profiles: Create as many profiles as needed for different Claude accounts
Multi-Profile Display: Show all profiles in the menu bar at once
Toggle between Single mode (active profile only) and Multi mode (all profiles)
Each profile displays with its own icon style and settings
Click any profile icon to view its usage details
Independent refresh rates per profile
Fun Auto-Names: Profiles auto-generate with names like "Quantum Llama", "Sneaky Penguin", "Turbo Sloth"
Custom Names: Rename profiles to whatever you prefer
Quick Switching: Switch profiles instantly via popover dropdown or settings sidebar
Profile Badges: Visual indicators show which profiles have Claude.ai credentials and CLI accounts
Claude Code CLI Integration
One-Click Sync: Sync your currently logged-in Claude Code account to a profile
Automatic Switching: When you switch profiles, CLI credentials automatically update
Credential Display: View masked access tokens and subscription type
Smart Re-Sync: Credentials automatically refresh before profile switches to capture CLI changes
Per-Profile CLI: Each profile can have its own Claude Code account or share the system account
Per-Profile Settings
Each profile has isolated settings:
Credentials: Separate Claude.ai session keys, API keys, and organization IDs
Appearance: Independent icon styles and monochrome mode
Automatic Migration: Seamless migration from old storage methods
Apple Code Signed: Verified by Apple for enhanced security and trust
Advanced Error Handling: Professional error system with user-friendly recovery
Robust Validation: Session key and API endpoint validation
Local storage with no cloud sync
Minimal anonymous analytics (version-only heartbeat every 24h — no PII, no credentials)
HTTPS-only communication with Claude API
Advanced Capabilities
Multi-screen support
First-run guided setup wizard
Protocol-based modular architecture
Persistent settings with App Groups
Comprehensive test coverage
Usage
Menu Bar Interface
Click the menu bar icon to access:
Session Usage: 5-hour rolling window percentage and reset time
Weekly Usage: Overall weekly consumption across all models
Opus Usage: Weekly Opus-specific usage (if applicable)
API Cost: Monthly cost with daily chart and per-key breakdown (if Console configured)
Quick Actions: Refresh and Settings
Settings
Access comprehensive settings through the menu bar popover → Settings button. The app features a modern sidebar interface with profile switcher and organized tabs:
Profile-Specific Settings
Profile Switcher (Sidebar)
Quick Profile Selection: Dropdown to switch between profiles instantly
Profile Badges: Visual indicators for Claude.ai 🔵 and CLI ✅ credentials
Active Profile Display: Shows currently selected profile
Claude.AI (Credentials)
Configure your Claude.ai personal account:
Browser Sign-In: Sign in via embedded browser to extract session key automatically (v3.0.2+)
Component Selection: Choose what to display (directory, branch, model name, context window, profile name, usage, progress bar, pace marker, reset time)
Color Mode: Multi-Color, Greyscale, or Single Color with custom hex picker
Pace Marker: 6-tier colored marker showing projected usage pace on progress bar
Label Toggles: Show/hide "Ctx:", "Usage:", "Reset:" prefixes for compact display
24-Hour Time: Optional 24-hour format for reset time
Live Preview: Terminal-matching preview with ANSI-equivalent colors
One-Click Install: Automated script installation to ~/.claude/
Automatic Updates: Statusline updates when switching profiles
Usage Cache: Instant CLI rendering via cached usage data
Bring real-time Claude usage monitoring directly into your terminal with Claude Code statusline integration! Display your current usage percentage, model name, context window, profile name, git branch, and working directory without leaving your development workflow.
What is Claude Code?
Claude Code is Anthropic's official CLI tool for interacting with Claude AI directly from your terminal. The statusline feature allows you to display custom information at the bottom of your terminal window.
Example: Terminal statusline with all components enabled
Session key configured: Must be manually configured in the Personal Usage tab (Claude Code OAuth doesn't work for statusline - it requires direct session key)
Installation Steps
Open Claude Usage Tracker Settings
Click the menu bar icon
Click "Settings"
Navigate to the "Claude Code" tab
Choose Your Components
Toggle on/off the components you want to see:
Directory name: Shows current working directory
Git branch: Displays current branch with ⎇ icon
Model name: Shows current model (Opus, Sonnet)
Profile name: Shows active profile name
Context window: Shows context usage as percentage or token count
Usage statistics: Shows session percentage with color coding
Progress bar: Visual 10-segment indicator (optional when usage is enabled)
Pace marker: Colored ┃ on progress bar at elapsed time position (6-tier pace colors)
Reset time: When your session resets (12h or 24h format)
Color mode: Choose Multi-Color, Greyscale, or Single Color
The application integrates with multiple Claude API endpoints for comprehensive usage tracking:
Web Usage Endpoint
hljs language-bash
GET https://claude.ai/api/organizations/{org_id}/usage
Authentication: Session cookie (sessionKey) from claude.ai
Response Structure:
five_hour: 5-hour session usage data
utilization_pct: Usage percentage (0-100)
reset_at: ISO 8601 timestamp for next reset
seven_day: Weekly usage across all models
utilization_pct: Weekly usage percentage
seven_day_opus: Opus-specific weekly usage
utilization_pct: Opus weekly percentage
extra_usage: Claude Extra cost tracking (if applicable)
current_spending: Amount spent
budget_limit: Maximum allowed spending
API Console Endpoint
hljs language-bash
GET https://api.anthropic.com/v1/organization/{org_id}/usage
Authentication: API Key (x-api-key header)
Response Structure:
API console usage statistics
Billing information
Rate limits and quotas
Dual Tracking
The app can simultaneously monitor both web (claude.ai) and API console usage, providing complete visibility into your Claude consumption across all access methods.
Automatic Migration: v2.0+ automatically migrates session keys from older storage methods to Keychain
Apple Code Signed: Officially signed with Apple Developer certificate for verified authenticity
Secure Updates: Automatic updates delivered over HTTPS with code signature verification
No Cloud Sync: All data remains local to your machine
Minimal Analytics: Anonymous heartbeat every 24 hours containing only the app version — no PII, no credentials, no usage data
Advanced Error Handling: Robust error system with user-friendly recovery
Session Key Validation: Comprehensive validation of API credentials
Network: HTTPS-only communication with claude.ai and Anthropic API
Troubleshooting
Application Not Connecting
Verify your session key is valid
Check that you're logged into claude.ai in your browser
Try extracting a fresh session key
Ensure you have an active internet connection
403 Permission Errors
If you see "Unauthorized" or 403 errors:
Open Settings → Personal Usage
Use the 3-step wizard to reconfigure:
Test your session key
Select the correct organization
Save configuration
The wizard will preserve your organization selection when updating keys
Menu Bar Icons Showing Zero
If icons briefly flash to zero during refresh:
This has been fixed in v2.1.0+
Update to the latest version for smooth refresh experience
Old data now stays visible until new data arrives
Menu Bar Icon Not Appearing
Check System Settings → Desktop & Dock → Menu Bar
Restart the application
Check Console.app for error messages
Session Key Expired
Session keys may expire after a period of time. You'll receive a notification 24 hours before expiry (v3.0.2+). To refresh:
Go to Settings → Personal Usage (or API Console)
Click "Sign in to Claude.ai" (or "Sign in to Anthropic Console") to re-authenticate via the built-in browser
Or expand "Advanced: Manual Session Key" to paste a new key manually
Updates Not Working
If automatic updates aren't working:
Check Settings → Updates to ensure automatic checking is enabled
Verify you're running v2.0.0 or later (earlier versions don't have auto-update)
Check your internet connection
Manually download the latest version from GitHub if needed
Contributors
This project is built for the community — everyone is welcome
Special Thanks
A huge thank you to everyone who contributed code, translations, bug reports, and pull requests. Your effort makes this project possible:
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Development Setup
Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request
Code Style
Follow Swift API Design Guidelines
Use SwiftUI best practices
Maintain MVVM architecture
Add comments for complex logic
Write descriptive commit messages
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
Built with Swift and SwiftUI
Designed for macOS Sonoma and later
Uses Claude AI's usage API
Inspired by the need for better usage visibility
Disclaimer
This application is not affiliated with, endorsed by, or sponsored by Anthropic PBC. Claude is a trademark of Anthropic PBC. This is an independent third-party tool created for personal usage monitoring.
AI Transparency
This project is developed using AI-assisted workflows (primarily Claude Code via Happy). We believe in transparent collaboration between human developers and AI tools.
