Tracks Claude's two usage clocks — the 5-hour rolling window and the weekly cap — and shows whichever is closer to its limit in the menu bar. Click it for both: percent used and time to reset, side by side.
Reads your Claude Code OAuth token from the macOS Keychain — the same system credential store the OS itself uses, not a plaintext file. Reading it triggers a macOS authorization prompt for your login password, and you can revoke access at any time in Keychain Access.app. Makes no network calls except to Anthropic's own endpoint. The source is short enough to read yourself before trusting it with your credentials.
Unofficial and not affiliated with Anthropic — built by
reverse-engineering an undocumented endpoint
(api.anthropic.com/api/oauth/usage
), so it may break without warning if that changes.
No dock icon, no settings, no telemetry.
Pick one — both end up with usagent.app
on disk.
- Grab the latest
usagent-X.Y.Z.zip
fromReleases. - Unzip it and move
usagent.app
to/Applications
. Right-click(don't double-click) the first time. macOS will warn it's from an unidentified developer — that's because the app is ad-hoc signed, not notarized with a paid Apple Developer ID. Clickusagent.app
→ OpenOpen anyway. This warning only appears once; after that it launches normally, including via Login Items.
After the first manual install, ./Scripts/update.sh
(or make update
) automates picking up new releases — see Update below.
Requires the Xcode command line tools (Swift 5.9+, macOS 13+).
git clone https://github.com/palamim/usagent.git
cd usagent
make app # builds usagent.app with a proper Info.plist (no dock icon)
make open # builds and opens it
A locally built app isn't quarantined by Gatekeeper (that only happens
to files downloaded through a browser), so no right-click-to-open step
is needed here. Move usagent.app
to /Applications
if you want it to live somewhere permanent.
make run
(plain swift run
) also works for quick iteration while developing — it flashes a dock icon briefly on launch since it isn't run from a bundle, which is expected and harmless.
swift test
runs the UsageStore
unit tests (state-machine behavior,
binding-clock selection) against a mocked UsageFetching
, no network
or Keychain access needed. Requires full Xcode.app, not just the
Command Line Tools — that's an XCTest requirement on macOS, not
something this project controls. CI (.github/workflows/tests.yml
) runs the suite on every push, since GitHub's macOS runners ship with Xcode preinstalled.
Once usagent.app
is somewhere permanent (e.g. /Applications
), add it to Login Items:
System Settings → General → Login Items & Extensions → Open at
Login → + → select usagent.app
.
If you rebuild from source, make app
overwrites the same path, so you won't need to re-add it as a login item afterward.
make update # or ./Scripts/update.sh
Downloads the latest GitHub release, quits any running usagent
,
replaces /Applications/usagent.app
with the new build, clears the
Gatekeeper quarantine flag so it opens without a right-click, then
reopens it. Prompts to add it to Login Items if it isn't already there.
Requires the gh
CLI, authenticated (gh auth login
).
The OAuth token lives in the macOS Keychain under the service name
Claude Code-credentials
, created by the Claude Code CLI — not by this app. The first time usagent reads it, macOS will prompt for your login password to authorize access. Click "Always Allow" (not "Allow") — otherwise you'll be prompted again on every launch or every refresh.
If you're prompted repeatedly even after that, the Keychain item's ACL may have been reset (e.g. after rebuilding with a different code signature). Re-authorizing once with "Always Allow" fixes it again.
Claude-Code-Usage-Monitor
invites native menu bar apps to consume its --write-state
output
instead of calling Anthropic's endpoint directly. We call the endpoint
directly instead: its own "official" data source for that state file is
the same OAuth usage endpoint (behind an opt-in --api
flag), so routing through it would mean running a separate Python tool as a background process for no benefit — just a dependency and a moving part this app doesn't need.
Worth naming the other prior art too: ccusage is the terminal tool most people reach for first, and does that well. usagent isn't trying to replace it — it covers the case a terminal or status-line tool doesn't: a persistent, at-a-glance menu bar indicator you're not running as a command.
Pro: what this app is built and tested against.five_hour
andseven_day
are the two clocks shown; everything else in the response isnull
and ignored.Max: should work unchanged for the two main clocks — same shape, higher limits. Max plans are also expected to populateseven_day_opus
, a separate (tighter) weekly sub-cap on Opus, which usagent shows as an extra "Weekly Opus" row and folds into the "closest to limit" calculation when present.This is implemented defensively but not verified against a real Max account— if the field's shape or meaning turns out to be different, please open an issue with a redacted response body.** Free**: out of scope. Free-tier accounts don't get Claude Code CLI access, so there's no OAuth token for this app to read in the first place.Team / Enterprise: unhandled. These likely use org-pooled limits rather than the personal five-hour/weekly windows this app is built around — probably a different feature, not a tweak.
- The endpoint (
https://api.anthropic.com/api/oauth/usage
) is undocumented. It could change or disappear without notice. - Refreshes on a 60s timer and on click, throttled to at most once per 15s to avoid hammering the endpoint.