Usage4Claude

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

---

✨ Features

🎯 Core Features

• 📊 Real-time Monitoring - Display Claude subscription’s 5-hour usage quota in menu bar
• 🎨 Smart Colors - Automatic color changes based on usage (green/orange/red)
• ⏰ Precise Timing - Quota reset time displayed with minute precision
• 🔄 Smart/Fixed Refresh - Intelligent 4-level adaptive refresh or fixed intervals (1/3/5/10 min)
• 💻 Native Experience - Pure native macOS app, lightweight and elegant

🌐 Cross-Platform Support

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!

🎨 Personalization

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

🔧 Convenient Features

• ⚙️ Visual Settings - No code modification needed, GUI configuration for all options
• 🆕 Auto Update Check - Stay up-to-date with latest versions and features
• 👋 Friendly Onboarding - Detailed setup wizard on first launch
• … Menu Display - Multiple menu access methods, detail view and right-click

🔒 Security & Privacy

• 🏠 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

---

📸 Screenshots

Menu Bar Display

Percentage Mode	Icon Mode	Combined Mode

Ring Color Indicators:

🟢 Green (0-69%) - Safe usage

🟠 Orange (70-89%) - Monitor usage

🔴 Red (90-100%) - Approaching limit

Detail Window

Settings

General - Customize display, refresh, and language options Authentication - Configure Claude account authentication About - Version info and related links

Welcome Screen

Set Up Authentication - Go directly to authentication settings to complete setup Set Up Later - Close welcome screen, configure later in settings

---

💾 Installation

Option 1: Download Pre-built (Recommended)

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 twice: Organization ID, Session Key)

Option 2: Build from Source

Requirements

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

Build Steps

# 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

---

📖 User Guide

Initial Setup

Launch App Welcome screen will appear on first run 1.

Configure Authentication Click “Go to Authentication Settings” button 1.

Get Required Info

• 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 and find:

• sessionKey=sk-ant-... value in Cookie

• Organization ID in URL (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Enter Information

• Paste Organization ID into “Organization ID” field
• Paste Session Key into “Session Key” field
• Monitoring will start automatically after configuration

Daily Usage

• Default Display - Menu bar shows usage percentage
• View Details - Click menu bar icon or percentage
• Show Menu - Click “…” icon in detail window or right-click menu bar icon
• Check Updates - Menu → Check for Updates
• Quit App - Menu → Quit

Refresh Mode

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

---

❓ FAQ

Q: What if the app shows “Session Expired”?

A: Session Keys expire periodically (usually weeks to months), need to re-obtain:

1. Open Settings → Authentication
2. Follow configuration guide to get new Session Key
3. Paste new Session Key Q: How to enable auto-launch on startup?

A:

1. Open System Settings → General → Login Items
2. Click “+” to add Usage4Claude Q: How much system resources does it use?

A: Very lightweight:

• CPU Usage: < 0.1% (idle)
• Memory: ~20MB
• Network: Only 1 request per minute Q: Which macOS versions are supported?

A: Requires macOS 13.0 (Ventura) or later. Supports both Intel and Apple Silicon (M1/M2/M3) chips.

Q: Why does it need Keychain permission?

A:

• Keychain is macOS’s system-level password manager
• Your Session Key and Organization ID are encrypted in Keychain
• This is Apple’s recommended secure storage method
• Only this app can access the information, other apps cannot view it Q: Is my data safe? How is privacy protected?

Completely safe!

Data Storage:

• All data stored only on your local Mac
• No collection, no tracking, no statistics of any information
• No network requests except Claude API calls
• No third-party services used

Authentication Security:

• Session Key encrypted via macOS Keychain (system-level encryption)
• Keychain uses AES-256 encryption + hardware protection (T2 / Secure Enclave)
• Only this app can access your credentials, other apps cannot read them
• You can revoke access anytime via “Keychain Access” app

Code Transparency:

• 100% open source
• No obfuscation or hidden features
• Community can audit and verify

Additional Protection:

• App Sandbox enabled (limits system access)
• No access to your files, contacts, or other apps
• Minimal permissions (only network + Keychain)

You can verify all of this by reviewing the source code on GitHub!

Q: Does it work with Claude Code / Desktop App / Mobile App?

A: Yes, it works with all Claude platforms!

Since all Claude products (Web, Claude Code, Desktop App, Mobile App) share the same 5-hour usage quota, Usage4Claude monitors your combined usage across all platforms.

Whether you’re:

• Coding in terminal with claude code
• Chatting on claude.ai
• Using the desktop app
• Using mobile apps

You’ll see your real-time total usage in the menu bar. No platform-specific configuration needed!

---

🛠 Tech Stack

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+

---

🗺 Roadmap

✅ Completed

• 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
• Keychain authentication storage

Short-term Plans

Feature Enhancement

• 🚧 Auto-launch on startup setting
• 🚧 Keyboard shortcuts

Developer

• 🚧 Shell auto-package DMG
• 🚧 GitHub Actions auto-release

Mid-term Plans

Display Optimization

• Settings interface
• Dark mode
• Detail window Focus state

Feature Addition

• 7-day usage monitoring support (OAuth・Opus)
• Usage notifications
• More language localizations

Long-term Vision

1. Auto Setup

• Browser extension for auto-authentication
• Automatic credential configuration

More Display Methods

• Desktop widgets
• Browser extension icon usage display

Data Analysis

• Usage history records
• Trend charts

Multi-platform Support

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

---

🤝 Contributing

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

For detailed contribution guidelines, please see CONTRIBUTING.md.

How to Contribute

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

Contributors

Thanks to all who have contributed to this project!

---

📝 Changelog

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

---

💖 Support

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

⭐ Star the Project

Giving a star is the biggest encouragement!

☕ Buy Me a Coffee

📢 Share the Project

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

---

📄 License

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.

---

🙏 Acknowledgments

• 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

---

📞 Contact

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

---

⚖️ Disclaimer

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.

---

If this project helps you, please give it a ⭐ Star!

Made with ❤️ by f-is-h

⬆ Back to Top