A tiny macOS gauge that shows how much of your Claude Code quota you've used — real-time, status-aware, and never lying with stale data.
Open source · MIT · reads only your usage, never your chats
Title stays silent when you're fine — one number, auto-contrast.
~. It never fakes freshness.
It only speaks up when it matters — and when it does, it tells the truth.
When you have headroom it's silent — just the current 5-hour percentage, auto black/white to match your menu bar. Cross a threshold and it surfaces the window that's actually biting, with a color and a reset countdown.
Claude Code doesn't refresh its keychain token while idle, so the usage API starts returning 401. ClaudeGauge spots a near-expired token and runs one tiny headless claude -p ok from /tmp to renew it — so the gauge keeps working even when you've stepped away.
If data is more than 15 minutes old, the title goes gray and grows a ~, and the dropdown warns you. No tool lies to you with old numbers dressed up as live — ever.
It reads one OAuth token from your macOS keychain and calls one Anthropic usage endpoint — the same one behind /usage. It never opens ~/.claude/projects, your conversations, or your code. No telemetry.
On notched Macs the menu bar title stays under ~90px (about 11 characters). Go wider and the notch swallows your icon whole — so the display is engineered to stay short no matter the state.
A background agent polls on an adaptive schedule and fires a native macOS notification the moment you cross 75% or 90% — once per window, per cycle, so it nudges without nagging.
Clone the repo and run the installer. It handles SwiftBar, the background refresher, and the first data pull.
# clone and install — macOS only
git clone https://github.com/EarthOnlineDev/claude-gauge.git
cd claude-gauge && ./install.sh
Needs macOS, a signed-in Claude Code with a Pro/Max subscription, and system python3.
Optional: point Claude Code's statusLine at the bridge for zero-cost instant updates while you work.
Uninstall anytime with ./uninstall.sh — it never touches your Claude Code credentials or data.
Each does one job. The render layer never touches the network when the background layer is healthy.
A SwiftBar plugin that wakes every 15 seconds, reads whichever of live.json or cache.json is newer, and draws the status-aware title and dropdown. Pure rendering — no secrets, no API calls in the happy path.
A LaunchAgent (dev.earthonline.claude-gauge) fires every 30s and adaptively throttles — 45s when critical, 240s when idle to dodge 429s. It polls the usage API, atomically writes the cache, self-heals the token, and sends threshold notifications.
Wired as Claude Code's statusLine command, it reads the rate limits CC already hands its status bar and writes live.json — so the menu bar updates instantly while you work, with no API call and no token needed. Applies to new sessions started after you configure it.
It's all readable bash and Python — nothing obfuscated, nothing hidden.
Reads one OAuth token from the keychain entry Claude Code-credentials and sends it only to Anthropic, only to fetch usage.
It never opens ~/.claude/projects, your conversation logs, or any code file. Usage numbers only.
Three short scripts in plain bash and Python — no minification, no binaries, no telemetry. Read every line before you run it.
Free to use, fork, and modify. Uninstall leaves your Claude Code credentials and data completely untouched.