ClaudeUsageMonitor · v2.2.1

A native macOS menu-bar app that tracks your Claude.ai usage in real time — no API key needed.

Changelog

v2.2.1

• Hourly update check — app now checks for new versions every hour in the background, not just at launch
• In-app download — when an update is available, click "Update Now" to download the DMG directly in the app; a progress bar is shown during download; click "Open & Install" when ready — Finder opens the DMG for a 1-step drag-install

v2.2.0

• Claude Design usage bar — new weekly progress bar for Claude Design usage, shown automatically when your plan has Claude Design allocation; tracks the seven_day_omelette bucket from the API

v2.1.0

• Daily routine runs — new progress bar tracking Claude Code Routine run budget per day (Pro: 5/day, Max: 15/day, Team/Enterprise: 25/day); shown automatically when your plan includes Routines
• Routine run notifications — alerts when 1 run remains and when all runs are exhausted for the day
• Data fetched from a dedicated API endpoint (/v1/code/routines/run-budget), plan limits are read directly from the API — no hardcoding

v2.0.0

• Direct API — migrated from DOM scraping + JS injection (WKWebView) to direct URLSession calls against Claude's internal REST API; faster, more reliable, no page-load delays
• Sonnet usage bar — dedicated weekly progress bar for Sonnet model usage (Max plan only), contributed by DukeOfCheese
• Extra usage bar — monthly credit spend progress when Extra Usage is enabled on your account, contributed by DukeOfCheese
• Cleaner auth flow — session key extracted once from login WKWebView; all subsequent requests are plain URLSession with no browser overhead

Demo

Features

• Menu-bar only — no Dock icon, stays out of your way
• Burn rate display — menu bar shows estimated time left (~45min left | 42%) based on actual usage pace; falls back to percentage when idle
• Colour-coded icon — green → orange → red as usage climbs
• Multi-bar dashboard — separate horizontal bars for Current session, Weekly limits (all models), Sonnet-specific usage (Max plan), and Claude Design usage
• Daily routine runs — tracks Claude Code Routine run budget per day (Pro: 5, Max: 15, Team/Enterprise: 25), shown automatically when your plan includes Routines
• Extra usage tracking — displays monthly credit spend progress when Extra Usage is enabled on your account
• Direct API — reads data straight from Claude's internal API; no DOM scraping, no JS injection
• Reset countdowns — "Resets in X hr Y min" for the session window; "Resets [Day] [Time]" for weekly limits
• Configurable auto-refresh — 30s / 1m / 2m / 5m / 10m, set via right-click menu
• Native notifications — contextual alerts at 75%, 80%, 90%, 95%, 100% usage, on session reset, and when routine runs are running low or exhausted
• Smart tip banner — in-popover tip that updates as usage climbs (75→80→90→95%)
• 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; checks every hour automatically
• One-click update download — "Update Now" downloads the DMG in-app with a progress bar; "Open & Install" opens it in Finder for drag-install (1 step)
• Persisted login — you only log in once; session is reused automatically

Installation (recommended — pre-built DMG)

Requires macOS 13 Ventura or later.

Step 1 — Download

Download the latest ClaudeUsageMonitor.dmg from the Releases page.

Step 2 — Install

1. Double-click ClaudeUsageMonitor.dmg to mount it
2. Drag ClaudeUsageMonitor into the Applications folder shortcut

Step 3 — First launch (Gatekeeper bypass)

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

You will not need to do this again after the first successful launch.

Step 4 — Log in to Claude

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 app icon appears in your menu bar.

Homebrew (alternative)

brew tap theDanButuc/tap
brew install --cask claude-usage-monitor

Usage

The left value shows estimated time left (burn rate) when active, or Current session % when idle. The right value is always Weekly limits %.

Left-click the icon to open the popover:

• Plan usage limits section with progress bars:
  • Current session — rate-limit window usage with "Resets in X hr Y min" countdown
  • Weekly limits / All models — billing-period usage with reset day and time (e.g. "Resets Fri 10:00 AM")
  • Sonnet — Sonnet-specific weekly usage (Max plan only)
  • Claude Design — weekly Claude Design usage bar, shown automatically when your plan includes a Claude Design allocation
  • Extra usage — monthly credit spend bar (X of Y credits), shown only when Extra Usage is enabled on your account
  • Daily routine runs — run budget bar for Claude Code Routines (shown when your plan includes Routines)
• Refresh button (↻) — force an immediate refresh
• 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

Building from source

You need Xcode Command Line Tools (free) — full Xcode is not required.

xcode-select --install   # if not already installed

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

Regenerate the app icon

swift scripts/make_icon.swift
# Produces /tmp/AppIcon.icns — copy to ClaudeUsageMonitor/Assets/AppIcon.icns

How it works

Data source

The app calls Claude's internal REST API directly:

• GET /api/organizations — resolves your organisation ID (cached after first call)
• GET /api/organizations/{org_id}/usage — returns utilization percentages and reset timestamps for all windows (five_hour, seven_day, seven_day_sonnet, seven_day_omelette, extra_usage)
• GET /v1/code/routines/run-budget — returns daily routine run budget (used / limit); called automatically after each usage refresh

Auth is via the sessionKey cookie, extracted from the login WKWebView after OAuth and stored in UserDefaults. All subsequent requests are plain URLSession calls — no WKWebView or JS injection at runtime.

Session persistence

On first launch a browser window opens so you can log in to Claude.ai. The sessionKey cookie is extracted and stored locally. If the session expires, the login window reappears automatically.

Troubleshooting

Project structure

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/
│   │   ├── ClaudeAPIService.swift    # URLSession-based API client (replaces WebScrapingService)
│   │   ├── NotificationService.swift # Usage threshold & reset notifications
│   │   └── UpdateService.swift       # GitHub Releases update check
│   ├── Views/
│   │   ├── ContentView.swift         # Popover UI (two-bar dashboard)
│   │   └── 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

Requirements

• macOS 13 Ventura or later
• An active Claude.ai account (Free, Pro, Team, or Max)
• Internet connection

License

MIT License. Feel free to use Claude Usage Monitor and contribute.

Acknowledgements

	DukeOfCheese — proposed the migration from DOM scraping to direct API calls, the Sonnet usage bar, and the extra usage bar (PR #3). These ideas shaped v2.0.0.