Usage4Claude

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

<div align="center"> <img src="docs/images/icon@2x.png" width="256" alt="icon">

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

</div>

---

✨ Features

🎯 Core Features

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

🌐 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)
• 🤝 Cowork (AI Agent)

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

🔒 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

• 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) | |:---:|:---:|:---:|:---:|:---:|:---:|-----| | <img src="docs/images/bar.icon@2x.png" width="40" height="40" alt="icon"> | <img src="docs/images/bar.5h@2x.png" width="45" height="45" alt="5h ring"> | <img src="docs/images/bar.7d@2x.png" width="45" height="45" alt="7d ring"> | <img src="docs/images/bar.ex@2x.png" width="45" height="45" alt="extra ring"> | <img src="docs/images/bar.7do@2x.png" width="45" height="45" alt="7d opus ring"> | <img src="docs/images/bar.7ds@2x.png" width="45" height="45" alt="7d sonnet ring"> | <img src="docs/images/bar.mono.b@2x.png" width="auto" height="35" alt="mono black"></br> <img src="docs/images/bar.mono.w@2x.png" width="auto" height="35" alt="mono white"> |

Color Indicators:

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

Detail Window

<table border="0"> <tr> <td align="top" valign="top"> <img src="docs/images/detail.5.en@2x.png" width="280" alt="5-Hour Limit Mode"> <br/><br/><br/><br/> _{<i>5-Hour Limit Mode</i>} </td> <td align="center" valign="top"> <img src="docs/images/detail.all.en@2x.png" width="280" alt="All Limits Mode"> <br/> _{<i>All Limits Mode (Any combination freely selectable)</i>} </td> <td align="center" valign="top"> <img src="docs/images/detail@2x.gif" width="280" alt="Time Remaining Toggle Animation"> <br/> _{<i>Time Remaining Toggle Animation</i>} </td> </tr> </table>

Settings

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

Welcome Screen

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

---

💾 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 once: 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

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

Daily Usage

• 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

Refresh Mod