ClaudeStatus

A macOS menu bar app that tracks your Claude subscription usage — the same numbers as the claude.ai profile usage screen.

• Menu bar: current session usage % and time until the session window resets, e.g. 4% · 2h 13m. The gauge icon turns orange/red when any limit is running hot.
• Click it: a panel with progress bars for the current session, the weekly all-models limit, and per-model weekly limits — each with reset times and warning colors — plus a projection of when you'd hit 100% at your current pace.
• Notifications: a banner when any limit crosses 70%, 90%, or 100% (once per reset window), and another when a nearly-full window resets. Requires running the installed .app (grant permission on first launch).
• Settings (gear in the panel): menu bar format (percent + countdown / percent / icon only), track the worst limit instead of the session, refresh interval, and notification toggles.

How it works

It reads the OAuth token that the Claude Code CLI stores in your login Keychain (service Claude Code-credentials) and polls Anthropic's OAuth usage endpoint (api.anthropic.com/api/oauth/usage) — every minute by default, configurable from 30s to 5min, with an immediate refresh on wake from sleep and when the panel opens. Nothing is stored or sent anywhere else, apart from a daily version check against GitHub releases.

Requirement: be signed in to the Claude Code CLI (claude) on this Mac. If the token expires, opening Claude Code once refreshes it.

Build & run

./build-app.sh            # builds dist/ClaudeStatus.app
./build-app.sh --install  # ...and copies it to /Applications
open dist/ClaudeStatus.app

For development: swift run ClaudeStatus, or swift run ClaudeStatus --check to print current usage to the terminal and exit.

"Start at login" (checkbox in the panel) requires running from an installed .app bundle, not swift run.

Install via Homebrew

Once the tap is set up (cask source in packaging/claudestatus.rb):

brew install --cask --no-quarantine codedrips/tap/claudestatus

--no-quarantine is needed until releases are notarized.

Releasing

./build-app.sh --release   # builds, zips, prints the sha256

The app checks GitHub releases once a day and shows an update link in the panel when a newer version is published. To cut a release:

1. Bump VERSION in build-app.sh.
2. ./build-app.sh --release — for a notarized build, first set SIGN_IDENTITY="Developer ID Application: …" and NOTARY_PROFILE=<profile> (created with xcrun notarytool store-credentials). Without them the zip is ad-hoc signed and downloads get quarantined by Gatekeeper.
3. gh release create v<version> dist/ClaudeStatus-<version>.zip --title v<version>
4. Update version and sha256 in packaging/claudestatus.rb and sync it to the tap.

The app icon is generated code: ./packaging/make-icon.sh redraws it (packaging/make-icon.swift) and rebuilds Resources/AppIcon.icns.