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 ✨

Features • Installation • User Guide • FAQ • Support

• 📊 Real-time Monitoring - Display Claude subscription's 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 (5-hour: green/orange/red; 7-day: purple gradient)
• ⏰ 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)

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
• 🛠️ 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 - Launch at login, customize display, theme settings, refresh, and language options Authentication - Configure Claude account authentication, connection diagnostics About - Version info and related links

Configure Authentication - Session Key, auto-retrieve Organization ID Configure Display Options - Display options and theme settings 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
   Click "Go to Authentication Settings" button

3. Get Session Key

   • Click "Open Claude Usage Page in Browser"
   • Open browser developer tools (press F12 or Cmd + Option + I)
   • Switch to "Network" tab
   • Refresh the page
   • Find request named usage
   • View Headers, find sessionKey=sk-ant-... value in Cookie

4. Enter Information

   • Paste Session Key into "Session Key" field
   • Monitoring will start automatically after configuration

• Default Display - Menu bar shows usage percentage
• View Details - Click menu bar icon or percentage
• Manual Refresh - Click refresh button in detail window or use shortcut ⌘R
• Show Menu - Click "…" icon in detail window or right-click menu bar icon
• 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

1. Developer Experience
   • 🚧 GitHub Actions check online version

2. Display Optimization

• 🚧 Settings interface dark mode adaptation

3. Feature Addition
   • Usage notifications
   • More language localizations

4. Auto Setup

• Browser extension for auto-authentication
• Automatic credential configuration

5. More Display Methods

• Desktop widgets
• Browser extension icon usage display

6. Data Analysis

   • Usage history records
   • Trend charts

7. 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.