Claude Usage

A lightweight macOS menubar app that displays your Claude Code usage limits at a glance — and alerts you when a Claude Code session needs your attention.

Built by @richhickson

• 📊 Session, Weekly & per-model limits - including model-scoped weekly caps (e.g. Fable/Opus) as Anthropic rolls them out
• 💵 Overage tracking - extra-usage spend against your monthly limit
• 🚦 Color-coded status - Green (OK), Yellow (>70%), Red (>90%)
• ⏱️ Time until reset for each limit
• 🔄 Auto-refresh every 5 minutes, with retry on network/keychain hiccups and refresh on wake from sleep

• 🔔 Menu bar bell with a count when Claude Code sessions are waiting for your permission or input
• 💬 macOS notifications when a session needs you - with an on/off toggle, permission status, and a test button
• 📋 Live session list in the popover: needs you 🔔 / working ⚙️ / finished ✅
• 🖱️ Click-to-focus - click a session (or its notification) to jump to the exact Terminal/iTerm2 tab it's running in; alerts clear once you've visited the session

• 📝 Edit your global CLAUDE.md - tell Claude Code how you like to work, from the app
• 🗓️ Conversation retention - set how long Claude Code keeps local transcripts (cleanupPeriodDays), preserving all your other settings

• 🚀 Launch at Login toggle and built-in update checker
• 🪶 Lightweight - Native Swift, minimal resources

1. Go to Releases
2. Download ClaudeUsage.zip
3. Unzip and drag ClaudeUsage.app to your Applications folder
4. Open the app (you may need to right-click → Open the first time)

git clone https://github.com/YOUR_USERNAME/claude-usage.git
cd claude-usage
open ClaudeUsage.xcodeproj

Then build with ⌘B and run with ⌘R.

• macOS 13.0 (Ventura) or later
• Claude Code CLI installed and logged in

1. Install Claude Code if you haven't already:

   npm install -g @anthropic-ai/claude-code

2. Log in to Claude Code:

   claude

3. Launch Claude Usage - it will read your credentials from Keychain automatically

1. Click the menu bar icon → gear icon → toggle Alert when a session needs attention
2. This installs a small status hook into ~/.claude/settings.json (pure POSIX sh, no dependencies; your existing settings and hooks are preserved, and toggling off removes it cleanly)
3. Allow notifications when prompted, and allow "ClaudeUsage wants to control Terminal" on your first click-to-focus - that's what jumps you to the right terminal tab
4. Hooks take effect for Claude Code sessions started (or resumed) after enabling

Tip: if you use macOS Focus modes, add ClaudeUsage to your Focus allowed apps or banners will be silenced.

Claude Usage reads your Claude Code OAuth credentials from macOS Keychain and queries the usage API endpoint at api.anthropic.com/api/oauth/usage.

Session alerts work via Claude Code's hooks system: a tiny shell script reports each session's status (working / needs attention / finished) to JSON sidecar files in ~/.claude/claudeusage/, which the app watches. Everything stays on your machine.

Note: This uses an undocumented API that could change at any time. The app will gracefully handle API changes but may stop working if Anthropic modifies the endpoint.

• Your credentials never leave your machine
• No analytics or telemetry
• No data sent anywhere except Anthropic's API
• Open source - verify the code yourself

Run claude in Terminal and complete the login flow.

Check if the app is running in Activity Monitor. Try quitting and reopening.

Click the refresh button (↻) in the dropdown. If still wrong, your Claude Code session may have expired - run claude again.

PRs welcome! Please open an issue first to discuss major changes.

MIT License - do whatever you want with it.

This is an unofficial tool not affiliated with Anthropic. It uses an undocumented API that may change without notice.

Made by @richhickson