// MACOS MENUBAR APP

Your Claude Code usage,
at a glance.

A tiny menubar app that shows your Claude Code session and weekly rate-limit usage — it reads directly from your macOS Keychain, so nothing ever leaves your machine.

View on GitHub → Install
GhostGauge menubar dropdown showing Claude Code session and weekly usage limits with reset times
// FEATURES

Everything you need to stay inside your limits.

▓

Session window

Your current 5-hour Claude Code session usage shown as a bar and percentage — right in the menubar. Know at a glance how much you have left.

5-hour windowLive bar
◉

Weekly — all models

7-day usage across all models, with the absolute reset timestamp. Never get caught off-guard by a reset on a Monday morning.

7-day windowReset time
◈

Sonnet only

When Sonnet usage data is present, GhostGauge surfaces it separately so you can track your most-used model independently.

SonnetPer-model
⟳

Auto-refresh

Polls the usage endpoint every 60 seconds so the numbers in your menubar stay current without you lifting a finger.

60s intervalBackground
◷

Local & private

Reads your Claude Code OAuth token from the macOS Keychain. The token never leaves your machine and is never logged or displayed — only the usage percentages are shown.

KeychainNo loggingOn-device
⊟

Menubar-native

Lives entirely in the macOS menubar — no Dock icon, no window chrome. Starts at login and stays out of your way until you need it.

Login itemNo Dock icon
// HOW IT WORKS

Three moves. No magic.

01
Read

Reads your token from Keychain

GhostGauge reads your Claude Code OAuth access token from the macOS Keychain (service name: Claude Code-credentials). The token is never displayed, never logged, and never leaves your machine.

Claude Code-credentials
02
Fetch

Calls the same endpoint Claude Code uses

Using that token, GhostGauge makes a single authenticated GET request to the Anthropic usage API — the exact same call Claude Code makes internally. Only the returned percentages and reset times are used.

GET https://api.anthropic.com/api/oauth/usage
03
Display

Shows usage in your menubar, every 60s

Session (5-hour window) and weekly (7-day window) percentages plus reset times appear directly in your macOS menubar. The app refreshes automatically every 60 seconds in the background.

// INSTALL

Built locally — no Gatekeeper prompt,
no Developer account, free.

Because GhostGauge is compiled on your own machine using uv, macOS never quarantines it — no Apple Developer account or code-signing required.

terminal 
$ git clone https://github.com/ghostshift-tech/ghostgauge.git
$ cd ghostgauge
$ ./install.sh

Requires uv to be installed. Or double-click install.command in Finder — same result.

Builds dist/GhostGauge.app, copies it to /Applications, and registers a Login Item — starts automatically at login.

Requires an active Claude Code login (claude) so the Keychain token exists.

View on GitHub →
// PRIVACY
Your token never leaves your machine.

GhostGauge reads your Claude Code OAuth access token from the macOS Keychain. It is never logged, never displayed, and never transmitted anywhere beyond the single authenticated request to Anthropic's usage endpoint.

Only the returned usage percentages and reset timestamps are stored in memory and shown in your menubar. The token itself is discarded immediately after the API call.

GhostGauge is not code-signed or notarized through Apple. It doesn't need to be — because it's built locally on your own machine by uv, macOS never quarantines it. Gatekeeper is sidestepped entirely, for free, without an Apple Developer account.

The full source is on GitHub. Read it, audit it, fork it.

MIT licensed · open source · no telemetry · no accounts