A lightweight macOS desktop widget that tracks your Claude usage limits and rate limits in real time. Know exactly when you're about to hit Claude's API usage cap — before it happens.
Claude usage limits are easy to hit without noticing. This widget keeps the important signals visible at all times:
- Current usage percentage
- Pace vs time elapsed
- Reset countdown timer
- Clear status color (green / orange / red)
No tab switching. No guesswork.
|
|
|
|
|
| On track — plenty of room | Compact mode | Window full — still usable | Session expired — re-authenticate |
- Live progress ring with usage %
- Pace tracking — actual vs expected usage
- Reset countdown timer
- Compact mode — double-click to shrink to a frameless ring; background appears on hover
- Always-on-top floating panel (all Spaces)
- Draggable — remembers position
- Auto-refresh every 30 seconds
- Session expiry detection with red border alert
- Cloudflare-aware — won't falsely show "Session Expired"
- Multi-limit aware — when one window is full, shows remaining capacity on other limits
- Self-updating — checks for updates every 24h, one-click update via Settings
- Plain-English status messages
- Minimal, translucent macOS-native UI
Four ways to get the widget — pick the one that fits:
brew install --cask rishi-banerjee1/ai-tools/claude-usage-widgetDon't have Homebrew? Install it first: brew.sh
curl -fsSL https://raw.githubusercontent.com/rishi-banerjee1/claude-usage-widget/main/install.sh | bashDownloads the pre-built app, installs to /Applications, removes Gatekeeper quarantine, and launches it. No build tools needed.
- Go to Releases
- Download
ClaudeUsage.app.zip - Unzip and move
ClaudeUsage.appto/Applications - Double-click to launch
macOS says "unidentified developer"? Right-click the app → Open → click Open again. That's it — you only need to do this once.
Requires macOS 13+ and Xcode Command Line Tools (xcode-select --install).
git clone https://github.com/rishi-banerjee1/claude-usage-widget.git
cd claude-usage-widget
chmod +x build.sh run.sh setup.sh generate-icon.sh
./build.sh
./setup.sh # Interactive credential setup
open build/ClaudeUsage.appThe widget needs two pieces of info from your Claude account (one-time setup, takes ~2 minutes):
- Launch the app — a small widget appears on your desktop
- Right-click the widget → Settings
- Paste your Session Key and Organization ID (see How to Get Your Credentials for step-by-step)
- Click Save
That's it — the widget shows your live usage data.
Session key expired? The widget shows a red border when this happens. Just right-click → Settings → paste a fresh key. Your Org ID never expires.
| Action | How |
|---|---|
| Open Settings | Right-click → Settings |
| Refresh | Right-click → Refresh |
| Quit | Right-click → Quit |
| Move widget | Click + drag |
| Compact / Full Size | Double-click widget, or right-click → Compact / Full Size |
| Change metric | Settings → Display Metric |
| Metric | Best For |
|---|---|
| 5-Hour (Recommended) | Daily pacing — tells you if you can keep chatting right now |
| 7-Day (All Models) | Weekly budgeting — tracks total weekly allowance |
| 7-Day (Sonnet Only) | Heavy Sonnet usage tracking |
You need two things from your browser. Here's how to find them:
- Open claude.ai in Chrome (make sure you're logged in)
- Press
Cmd + Option + Ito open Developer Tools - Click the Application tab at the top
- In the left sidebar, expand Cookies → click https://claude.ai
- Find the row named
sessionKey→ double-click the Value column → copy it
Session keys expire every few days. When the widget shows a red border, just paste a fresh key in Settings.
- Still in Developer Tools, click the Network tab at the top
- Send any message in a Claude chat
- Look at the request URLs that appear — find one containing
/organizations/ - The long code after
/organizations/is your Org ID (looks likexxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
Your Org ID never expires — you only need to do this once.
| Principle | Detail |
|---|---|
| No browser access | The app never reads your cookies or browser data — you paste the key yourself |
| Masked input | Session key is hidden when you type it and never logged |
| Keychain storage | Session key stored securely in macOS Keychain — no repeated password prompts |
| No telemetry | Zero analytics, zero tracking. The app only talks to claude.ai |
| Cloudflare-aware | Handles Cloudflare security checks gracefully — won't falsely report your session as expired |
| Smart polling | Pauses API calls when session expires — resumes when you save fresh credentials |
| Open source | Read every line of setup.sh and ClaudeUsageApp.swift |
Understanding Claude Limits
Claude enforces two independent limits:
- Tracks the last 5 hours of usage
- Recovers automatically as time passes
- Most useful for daily pacing
- If it hits 100% — you're locked out until older messages age past the 5-hour mark
- Total weekly allowance across all models
- Hard reset once per week
- If it hits 100% — you're done until the weekly reset regardless of the 5-hour limit
There's also a 7-Day Sonnet-only metric for tracking that model separately.
The widget compares your actual usage vs expected usage based on elapsed time:
| Color | Meaning | Example |
|---|---|---|
| 🟢 Green | More than 5% below expected pace | 2h into 5h window, at 30% (expected: 40%) |
| 🟠 Orange | Within ±5% of expected pace | 2h into 5h window, at 38% (expected: 40%) |
| 🔴 Red | More than 5% above expected pace | 2h into 5h window, at 60% (expected: 40%) |
| Message | Meaning |
|---|---|
| Plenty of room | Under 30%, on track |
| On track — you're good | On track, above 30% |
| On pace — be mindful | Roughly at expected pace |
| Above pace — slow down | Burning faster than expected |
| Almost out — slow down | Above 90%, exceeding pace |
| Limit reached — wait for reset | 100% — rate-limited |
What Happens When setup.sh Can't Auto-Fetch
Sometimes setup.sh can't automatically fetch your org ID. Here's why and what to do:
The Claude API sits behind Cloudflare, which occasionally challenges curl requests with a 403 page. This does NOT mean your session key is invalid.
setup.shwill detect the Cloudflare block and tell you- It will ask you to enter your org ID manually instead (with step-by-step instructions)
- The widget app itself uses macOS
URLSessionwhich passes through Cloudflare — so the widget will work fine even ifcurlwas blocked
If the session key you pasted has already expired:
setup.shwill detect the 401/403 error and tell you it's expired- You'll be prompted to paste a fresh key and try again
- If it still fails, you can save anyway — the widget will show "Session Expired" and prompt you to update later
If your network is down or the API is unreachable:
setup.shoffers manual entry as a fallback- The widget retries with exponential backoff (1s → 2s → 4s) up to 3 times
Manual Setup (Alternative to setup.sh)
If you prefer not to use the setup script:
- Right-click the widget → Settings...
- Paste your Session Key (from browser cookies — see How to Get Your Credentials)
- Paste your Organization ID (from DevTools Network tab, or env var)
- Select which metric to display
- Click Save
export CLAUDE_SESSION_KEY="sk-ant-sid01-..."
export CLAUDE_ORGANIZATION_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
open build/ClaudeUsage.appHow It Works (Technical)
The widget polls the Claude API every 30 seconds:
GET https://claude.ai/api/organizations/{orgId}/usage
Cookie: sessionKey={key}
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ClaudeUsageWidget/1.0
Architecture: Single-file Swift app (ClaudeUsageApp.swift, ~1610 lines) — no Xcode project, no dependencies, no package manager. Compiles with swiftc directly.
Key components:
FloatingWidgetPanel— borderlessNSPanel(always-on-top, all Spaces, draggable)WidgetView— SwiftUI with 4 states + compact/full mode, data, setup needed, session expired, loadingWidgetPanelController— manages lifecycle, persists position, handles compact toggle + panel resizeAppDelegate— fetching, 30s timer, retry logic, Cloudflare detection
| Issue | Fix |
|---|---|
| "Setup Needed" | Right-click the widget → Settings → enter your credentials |
| "Session Expired" (red border) | Right-click → Settings → paste a fresh session key. Your Org ID is remembered. |
| Widget not visible | The app has no dock or menubar icon — just the floating widget. Try relaunching the app. |
| Widget too big | Double-click to switch to compact mode (just the ring). Double-click again to restore. |
| Data not loading | Usually an expired session key — right-click → Settings → paste a fresh one |
| Stuck at same % | That's accurate — usage recovers gradually over the time window. Try switching metrics via right-click. |
| macOS blocks the app | Right-click the app → Open → click Open again |
| Build fails (SwiftBridging) | sudo rm -rf /Library/Developer/CommandLineTools && xcode-select --install |
| Widget gone after restart | Launch at Login is enabled by default. If you disabled it, re-enable via right-click → Settings |
- Keychain storage for session key — migrated from UserDefaults
- Launch at Login — enabled by default via
SMAppService, toggleable in Settings - In-app update notifications — blue dot indicator + one-click self-update via Settings
- Compact mode — frameless ring, double-click or right-click to toggle
- One-command installer + GitHub Releases distribution
- Optional usage history graph
- Signed / notarized build
- Homebrew cask —
brew install --cask rishi-banerjee1/ai-tools/claude-usage-widget
Built by @rishi-banerjee1.
MIT