A macOS menu bar app showing three Claude usage bars at a glance: current session (5-hour window), weekly all-models, and weekly Fable — the same numbers as claude.ai → Settings → Usage, without having to go and look.
It also tells you what a percentage alone can't: how fast you're burning it, whether you'll run out before the window resets, and which of your projects and models is responsible.
Burn rate and projection. 72% four hours into a window is fine; 72% forty minutes in is a problem. The app keeps its own history and works out the difference — "on pace to cap at 12:05" appears when the current rate would exhaust a limit before it resets.
Notifications, all optional, off-switchable individually, with quiet hours:
- Threshold bands (80% and 95% by default), once per limit per window
- A limit reset — useful, because that's when you can start the big job
- Burning unusually fast, measured against your own median rate for the past week rather than a fixed number
What's driving usage. Reads Pi and Claude Code session logs on this Mac and attributes recent usage by project and by model, so "why is Fable at 86%" has an answer. Token counts are weighted to reflect how the classes are priced, since raw totals are dominated by cheap cache reads.
This part is a local proxy, not the truth: anything you do on claude.ai, on mobile, or on another Mac cannot be seen, and Anthropic doesn't publish how tokens map onto limit percentages, so shares are relative to what was observed locally.
Bars turn amber at 75% and red at 90%. The icon stays quiet until something is pressing, then shows the percentage.
brew install johnwards/tap/claudeusage
brew services start claudeusagebrew services starts it now and at every login.
brew update && brew upgrade claudeusage
brew services restart claudeusageThe restart matters. brew upgrade replaces the files on disk, but macOS
leaves the old process running off the deleted binary, so without a restart
you keep running the previous version until your next login.
git clone https://github.com/johnwards/claudeusage.git
cd claudeusage
./build.sh
open build/ClaudeUsage.appTo start it at login: System Settings → General → Login Items → add
build/ClaudeUsage.app.
Either way you're compiling locally, so macOS doesn't quarantine the binary
and Gatekeeper stays out of your way. Requires the Xcode command line tools
(xcode-select --install).
Click the menu bar icon → "Sign in with Claude…". That opens the normal
Anthropic OAuth flow in your browser; approve it and the app catches the
redirect on localhost:53692. If that fails — port in use, or your browser
is on another machine — use "Paste authorization code…" and paste what
claude.ai shows you.
It polls https://api.anthropic.com/api/oauth/usage every 60 seconds and
whenever you open the menu. No cookies, no scraping — it's the same endpoint
the Claude apps use, authorised with your own OAuth token.
It uses Claude Code's OAuth client ID. There's no public client registration for third-party apps, so this app identifies itself using the same public client ID that Claude Code, Pi, OpenCode and similar tools use. You sign in with your own Claude account and the token is yours alone, but this is not an officially sanctioned integration and Anthropic could restrict it at any point.
Your token is stored in a plain file, at
~/Library/Application Support/ClaudeUsage/credentials.json, mode 0600.
Not the Keychain: these builds are ad-hoc signed and get a new signature on
every rebuild, and Keychain ACLs are bound to the signature, so each read
would prompt for your password. Any process running as your user can read
that file — the same trade-off Claude Code and similar CLI tools make. A
notarized build could switch back to the Keychain.
"Sign out" deletes the file.
MIT