English | 日本語 | 简体中文 | 繁體中文 | 한국어

An elegant macOS menu bar app for real-time monitoring of your Claude AI usage.

✨ Monitors all Claude platforms: Web • Claude Code • Desktop • Mobile App • Cowork ✨

Features • Installation • User Guide • FAQ • Support

• 📊 Real-time Monitoring - Display Claude subscription (Free/Pro/Team/Max) usage quota in menu bar
• 🎯 Multi-Limit Support - Show up to 5 limits simultaneously (5-hour/7-day/Extra/7-day Opus/7-day Sonnet)
• 🎨 Smart Display Mode - Auto-detect and display all limit types with available data
• ⚙️ Custom Display - Manually select which limit types to display, supports any combination
• 🎨 Smart Colors - Automatic color changes based on usage, each limit type has its own color scheme
• 🔔 Usage Notifications - Warning notification at 90% usage, reset notification when quota resets
• 👥 Multi-Account Management - Support multiple accounts / multiple organizations per account, quick switching
• 🌐 Built-in Browser Login - Built-in browser login to automatically extract Session Key, no manual copying needed
• 🎨 Appearance Settings - Support system default / light / dark appearance modes
• 🕐 Time Format - Support system default / 12-hour / 24-hour format
• ⏰ Precise Timing - Quota reset time displayed with minute precision
• 🔄 Smart Refresh System - Intelligent 4-level adaptive refresh or fixed intervals (1/3/5/10 min)
• ⚡ Manual Refresh - Click refresh button to update data instantly (10-second debounce protection)
• 💻 Native Experience - Pure native macOS app, lightweight and elegant

Works seamlessly with all Claude products:

• 🌐 Claude.ai (Web interface)
• 💻 Claude Code (CLI tool for developers)
• 🖥️ Desktop App (macOS/Windows)
• 📱 Mobile App (iOS/Android)
• 🤝 Cowork (AI Agent)

All platforms share the same usage quota, monitored in one place!

• 🕓 Multiple Display Modes

  • Percentage Only - Clean and intuitive, view at a glance
  • Icon Only - Subtle and elegant, detailed info on click
  • Icon + Percentage - Complete information, quick visual identification

• 🌍 Multilingual Support

  • English
  • 日本語
  • 简体中文
  • 繁体中文
  • 한국어
  • More languages coming soon...

• ⚙️ Visual Settings - No code modification needed, GUI configuration for all options
• 🆕 Smart Update Alerts - Menu bar badge and rainbow animation notify new versions
• 🚀 Launch at Login - Optional automatic startup when system boots
• ⌨️ Keyboard Shortcuts - Common operations support shortcuts (⌘R, ⌘,, ⌘Q)
• 👋 Friendly Onboarding - Detailed setup wizard on first launch
• … Menu Display - Multiple menu access methods, detail view and right-click
• 🔔 Usage Notifications - Usage warning and reset notifications, configurable in settings
• 🛠️ Debug Mode - Developer options: fake data testing, simulated updates, instant refresh

• 🏠 Local Storage Only - All data stored locally only, never collect or upload any personal information
• 🔐 Keychain Protection - Sensitive information secured in Keychain, no plain text keys
• 📖 Open Source Transparency - Code fully public, anyone can audit
• 🛡️ Sandbox Protection - App Sandbox enabled for enhanced security

• Icons and any limit type can be freely combined for display (at least one item must be shown)
• Dual indicators through shape and color ensure easy identification even in monochrome themes

Icon	5-Hour	7-Day	Extra	7-Day Opus	7-Day Sonnet	Monochrome (Adaptive)

Color Indicators:

• 5-Hour Limit (incl. detail window): → →
• 7-Day Limit (incl. detail window): → →
• Extra Usage: → →
• 7-Day Opus Limit: → →
• 7-Day Sonnet Limit: → →

5-Hour Limit Mode

All Limits Mode (Any combination freely selectable)

Time Remaining Toggle Animation

General - Display options, menu bar theme, notification settings, appearance (system/light/dark), refresh mode, time format, language options, launch at login Authentication - Multi-account management (add/delete/switch/alias editing), built-in browser login, manual input, connection diagnostics About - Version info and related links

Configure Authentication - Built-in browser one-click login (recommended) or manual Session Key input, auto-retrieve Organization ID, auto-create multiple organizations under same Session Key Configure Display Options - Menu bar theme, display content, display mode (smart/custom) selection with live preview Set Up Later - Close welcome screen, configure later in settings

1. Go to Releases page
2. Download the latest .dmg file
3. Double-click to open, drag app to Applications folder
4. Right-click the app and select "Open" on first launch (allow unsigned app)
5. Allow Keychain access for authentication info (Need to allow again after version updates. Authorization prompt appears once: Session Key)

• macOS 13.0 or later
• Xcode 15.0 or later
• Git

# Clone repository
git clone https://github.com/f-is-h/Usage4Claude.git
cd Usage4Claude

# Open in Xcode
open Usage4Claude.xcodeproj

# Press Cmd + R to run in Xcode

1. Launch App Welcome screen will appear on first run

2. Configure Authentication

   • Option 1: Browser Login (Recommended)
     • Click the "Browser Login" button
     • Log in to your Claude account in the built-in browser
     • Session Key will be automatically extracted after successful login
   • Option 2: Manual Input
     • Open browser and visit the Claude usage page
     • Open developer tools (F12 or Cmd + Option + I)
     • Switch to "Network" tab, refresh the page
     • Find the usage request, extract sessionKey=sk-ant-... from Cookie
     • Paste into the input field

• Default Display - Menu bar icon shows usage percentage
• View Details - Click menu bar icon to view details
• Manual Refresh - Click refresh button in detail window or use shortcut ⌘R (data also auto-refreshes when opening the main window)
• Switch Account - Click "…" menu in detail window or right-click menu bar icon to select account
• Keyboard Shortcuts
  • ⌘R - Manual refresh data
  • ⌘, - Open General Settings
  • ⌘⇧A - Open Authentication Settings
  • ⌘Q - Quit app
• Update Alerts - When new version available, menu bar icon shows badge and menu items display rainbow text
• Check Updates - Menu → Check for Updates

Smart Frequency (Recommended)

• Automatically adjusts refresh rate based on usage patterns
• Active mode (1 min) - Fast refresh when actively using Claude
• Idle modes (3/5/10 min) - Progressively slower refresh when idle
• Significantly reduces API calls during idle periods (up to 10x)
• Instantly returns to 1-minute refresh when usage detected

Fixed Frequency

• 1 minute - Recommended for consistent monitoring
• 3 minutes - Balanced monitoring
• 5 minutes - Low frequency monitoring
• 10 minutes - Minimal API calls

Built with modern macOS native technologies:

• Language: Swift 5.0+
• UI Framework: SwiftUI + AppKit hybrid
• Architecture: MVVM
• Networking: URLSession
• Reactive: Combine Framework
• Localization: Built-in i18n support
• Platform: macOS 13.0+

• Basic monitoring features
• Menu bar real-time display
• Circular progress indicator
• Smart color alerts
• Real-time countdown
• Multiple menu bar display modes
• Visual settings interface
• Multilingual support
• First-launch onboarding
• Update checking with visual alerts
• Keychain authentication storage
• Shell auto-package DMG
• GitHub Actions auto-release
• Settings interface display optimization
• Launch at login option
• Keyboard shortcuts support
• Manual refresh feature
• Three-dot menu dark mode adaptation
• Dual limit mode support (5-hour + 7-day)
• Dual-ring menu bar icon
• Unified color scheme management
• Debug mode (fake data, simulated updates)
• Detail window remove Focus state
• Multi-limit type support (5 types)
• Smart/custom display mode
• Auto-retrieve Organization ID
• Optimized welcome flow
• Monochrome theme icon display
• Korean language support
• GitHub Actions check online version
• Appearance settings (system/light/dark)
• Built-in browser auto-authentication
• Automatic credential configuration
• Usage notifications
• Multi-account management
• Unified time format settings
• Settings interface dark mode adaptation

1. Feature Addition
   • More language localizations

2. More Display Methods

   • Desktop widgets
   • Browser extension icon usage display

3. Data Analysis

   • Usage history records
   • Trend charts

4. Multi-platform Support

   • iOS / iPadOS version
   • Apple Watch version
   • Windows version

All contributions are welcome! Whether it's new features, bug fixes, or documentation improvements.

For detailed contribution guidelines, please see CONTRIBUTING.md.

1. Fork this repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Thanks to all who have contributed to this project!

For detailed version history and updates, please see CHANGELOG.md.

If this project helps you, please support in the following ways:

Giving a star is the biggest encouragement!

If you like this project, please share it with more people!

This project is licensed under the MIT License - see LICENSE file for details

MIT License

Copyright (c) 2025 f-is-h

You are free to use, copy, modify, merge, publish, distribute, sublicense, 
and/or sell copies of the Software.

• Thanks to Claude AI - Most code written by AI
• Thanks to all contributors and users for their support
• Icon design inspired by Claude AI official branding

• Issues: Submit issues or suggestions
• Discussions: Join discussions
• GitHub: @f-is-h

This project is an independent third-party tool with no official affiliation with Anthropic or Claude AI. Please comply with Claude AI's Terms of Service when using this software.