A native macOS menu-bar app that tracks your Claude.ai usage in real time — no API key needed.
- Menu-bar only — no Dock icon, stays out of your way
- Live usage counter — shows
used/limit(e.g.45/100) right in the menu bar - Colour-coded tree icon — green → yellow → red as usage climbs
- Popover dashboard — circular progress ring, reset countdown, stats cards
- Session-aware — captures Claude's internal rate-limit window via a fetch interceptor, not just the billing-period total
- Configurable auto-refresh — 30s / 1m / 2m / 5m / 10m, set via right-click menu
- Native notifications — alerts at 80%, 90%, 100% usage and on session reset
- Live reset countdown — "Resets in Xh Ym" updates every minute while the popover is open; reset time sourced directly from Claude's API
- Stale data indicator — icon turns grey and shows ⚠ if data is older than 10 minutes
- Right-click context menu — quick usage info and settings without opening the popover
- In-app update banner — notified when a new version is available on GitHub
- Persisted login — WebKit stores your Claude session automatically; you only log in once
Requires macOS 13 Ventura or later.
Download the latest ClaudeUsageMonitor.dmg from the Releases page.
- Double-click
ClaudeUsageMonitor.dmgto mount it - Drag ClaudeUsageMonitor into the Applications folder shortcut
Because the app is ad-hoc signed (not yet notarized with an Apple Developer ID), macOS will block it on first open.
Do this once:
Right-click ClaudeUsageMonitor.app → Open → Open
Or via Terminal:
xattr -cr /Applications/ClaudeUsageMonitor.app
open /Applications/ClaudeUsageMonitor.appYou will not need to do this again after the first successful launch.
A browser window opens automatically on first run. Log in to your Claude.ai account normally. The window closes by itself when login succeeds and the tree icon appears in your menu bar.
brew tap theDanButuc/tap
brew install --cask claude-usage-monitor| Element | Meaning |
|---|---|
🌲 Green 45/100 |
Plenty of messages left (< 50 % used) |
🌲 Yellow 67/100 |
Getting there (50 – 80 % used) |
🌲 Red 88/100 |
Almost out (> 80 % used) |
🌲 Grey ⚠ 45/100 |
Data is stale (last update > 10 min ago) |
Left-click the icon to open the popover:
- Circular ring — current session usage percentage
- Resets in X h Y m — time until the next usage window resets
- Period total card — billing-period total (when session data is available separately)
- Rate limit badge — Normal / Limited
- Refresh button (↻) — force an immediate scrape
- Quit button — exit the app
Right-click the icon for a quick context menu:
- Current usage and reset countdown at a glance
- Refresh Interval submenu — choose 30s / 1m / 2m / 5m / 10m (persisted across launches)
- Refresh Now — immediate refresh
- Quit
You need Xcode Command Line Tools (free) — full Xcode is not required.
xcode-select --install # if not already installedClone and build:
git clone https://github.com/theDanButuc/Claude-Usage-Monitor.git
cd Claude-Usage-Monitor
bash scripts/build.sh # native arch (arm64 or x86_64)
bash scripts/build.sh --universal # universal binary (arm64 + x86_64)Produces dist/ClaudeUsageMonitor-vX.X.X.dmg ready to install.
swift scripts/make_icon.swift
# Produces /tmp/AppIcon.icns — copy to ClaudeUsageMonitor/Assets/AppIcon.icnsbrew install xcodegen
xcodegen generate # creates ClaudeUsageMonitor.xcodeproj
open ClaudeUsageMonitor.xcodeprojThe app embeds a hidden WKWebView that loads claude.ai/settings/usage using your stored browser session (via WKWebsiteDataStore.default() — the same cookie store Safari uses for WebKit-based apps).
A JavaScript fetch/XHR interceptor is injected at document start, before any page script runs. It captures every API response that mentions usage, limits, or quotas and forwards the raw JSON to Swift. This gives session-window data (e.g. the 5-hour rate-limit window) not visible in the page's DOM text. A DOM-text extraction pass runs 5 s after page load as a fallback.
WKWebsiteDataStore.default() persists cookies to disk between app launches automatically — no manual Keychain work needed. If the session expires, the login window reappears.
| Symptom | Fix |
|---|---|
| "Cannot be opened because the developer cannot be verified" | Right-click → Open, or run xattr -cr /Applications/ClaudeUsageMonitor.app |
| Login window keeps appearing | Your Claude session expired — log in again |
Shows 0/0 or no numbers |
Claude.ai's page changed; open a GitHub Issue with your macOS version |
| Icon missing from menu bar | Quit via the popover's Quit button and re-open the app |
| App won't launch after macOS update | Rebuild from source with the updated SDK |
ClaudeUsageMonitor/
├── ClaudeUsageMonitor/
│ ├── ClaudeUsageMonitorApp.swift # @main entry point
│ ├── AppDelegate.swift # Status bar, popover, refresh timer
│ ├── LoginWindowController.swift # Full-screen login WebView
│ ├── Models/
│ │ └── UsageData.swift # Data model + computed helpers
│ ├── Services/
│ │ ├── WebScrapingService.swift # WKWebView + JS interceptor
│ │ ├── NotificationService.swift # Usage threshold & reset notifications
│ │ └── UpdateService.swift # GitHub Releases update check
│ ├── Views/
│ │ ├── ContentView.swift # Popover UI
│ │ └── CircularProgressView.swift
│ ├── Assets/
│ │ └── AppIcon.icns # All 10 icon sizes
│ ├── Info.plist
│ └── ClaudeUsageMonitor.entitlements
├── scripts/
│ ├── build.sh # Local build + DMG script
│ └── make_icon.swift # Icon generator (Swift script)
├── screenshots/
│ └── popover.png # App screenshot
├── .github/workflows/
│ ├── release.yml # CI: build & publish DMG on git tag
│ └── update-homebrew-tap.yml # CI: update Homebrew cask after release
├── project.yml # XcodeGen spec
└── .gitignore
- macOS 13 Ventura or later
- An active Claude.ai account (Free, Pro, Team, or Max)
- Internet connection
MIT — use freely, attribution appreciated.