{"slug": "show-hn-a-macos-menu-bar-app-showing-claude-subscription-usage", "title": "Show HN: A macOS menu bar app showing Claude subscription usage", "summary": "A new open-source macOS menu bar app, usagent, tracks Claude subscription usage by displaying the closer of the 5-hour rolling window or weekly cap, with percent used and time to reset. Built by reverse-engineering an undocumented Anthropic endpoint, it reads the Claude Code OAuth token from the macOS Keychain and makes no network calls except to Anthropic's own endpoint. The app is unofficial, ad-hoc signed, and available via GitHub releases or building from source.", "body_md": "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.\n\nReads 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.\n\n**Unofficial and not affiliated with Anthropic** — built by\nreverse-engineering an undocumented endpoint\n(`api.anthropic.com/api/oauth/usage`\n\n), so it may break without warning\nif that changes.\n\nNo dock icon, no settings, no telemetry.\n\nPick one — both end up with `usagent.app`\n\non disk.\n\n- Grab the latest\n`usagent-X.Y.Z.zip`\n\nfrom[Releases](https://github.com/palamim/usagent/releases). - Unzip it and move\n`usagent.app`\n\nto`/Applications`\n\n. **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. Click`usagent.app`\n\n→ Open**Open** anyway. This warning only appears once; after that it launches normally, including via Login Items.\n\nAfter the first manual install, `./Scripts/update.sh`\n\n(or `make update`\n\n)\nautomates picking up new releases — see [Update](#update) below.\n\nRequires the Xcode command line tools (Swift 5.9+, macOS 13+).\n\n```\ngit clone https://github.com/palamim/usagent.git\ncd usagent\nmake app     # builds usagent.app with a proper Info.plist (no dock icon)\nmake open    # builds and opens it\n```\n\nA locally built app isn't quarantined by Gatekeeper (that only happens\nto files downloaded through a browser), so no right-click-to-open step\nis needed here. Move `usagent.app`\n\nto `/Applications`\n\nif you want it to\nlive somewhere permanent.\n\n`make run`\n\n(plain `swift run`\n\n) also works for quick iteration while\ndeveloping — it flashes a dock icon briefly on launch since it isn't\nrun from a bundle, which is expected and harmless.\n\n`swift test`\n\nruns the `UsageStore`\n\nunit tests (state-machine behavior,\nbinding-clock selection) against a mocked `UsageFetching`\n\n, no network\nor Keychain access needed. Requires full **Xcode.app**, not just the\nCommand Line Tools — that's an XCTest requirement on macOS, not\nsomething this project controls. CI (`.github/workflows/tests.yml`\n\n)\nruns the suite on every push, since GitHub's macOS runners ship with\nXcode preinstalled.\n\nOnce `usagent.app`\n\nis somewhere permanent (e.g. `/Applications`\n\n), add\nit to Login Items:\n\n**System Settings → General → Login Items & Extensions → Open at\nLogin → +** → select `usagent.app`\n\n.\n\nIf you rebuild from source, `make app`\n\noverwrites the same path, so you\nwon't need to re-add it as a login item afterward.\n\n```\nmake update    # or ./Scripts/update.sh\n```\n\nDownloads the latest GitHub release, quits any running `usagent`\n\n,\nreplaces `/Applications/usagent.app`\n\nwith the new build, clears the\nGatekeeper quarantine flag so it opens without a right-click, then\nreopens it. Prompts to add it to Login Items if it isn't already there.\nRequires the `gh`\n\nCLI, authenticated (`gh auth login`\n\n).\n\nThe OAuth token lives in the macOS Keychain under the service name\n`Claude Code-credentials`\n\n, created by the Claude Code CLI — not by this\napp. The first time usagent reads it, macOS will prompt for your login\npassword to authorize access. **Click \"Always Allow\"** (not \"Allow\") —\notherwise you'll be prompted again on every launch or every refresh.\n\nIf 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.\n\n[Claude-Code-Usage-Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor)\ninvites native menu bar apps to consume its `--write-state`\n\noutput\ninstead of calling Anthropic's endpoint directly. We call the endpoint\ndirectly instead: its own \"official\" data source for that state file is\nthe same OAuth usage endpoint (behind an opt-in `--api`\n\nflag), so\nrouting through it would mean running a separate Python tool as a\nbackground process for no benefit — just a dependency and a moving\npart this app doesn't need.\n\nWorth naming the other prior art too: [ccusage](https://github.com/ryoppippi/ccusage)\nis the terminal tool most people reach for first, and does that well.\nusagent isn't trying to replace it — it covers the case a terminal or\nstatus-line tool doesn't: a persistent, at-a-glance menu bar indicator\nyou're not running as a command.\n\n**Pro**: what this app is built and tested against.`five_hour`\n\nand`seven_day`\n\nare the two clocks shown; everything else in the response is`null`\n\nand ignored.**Max**: should work unchanged for the two main clocks — same shape, higher limits. Max plans are also expected to populate`seven_day_opus`\n\n, 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.\n\n- The endpoint (\n`https://api.anthropic.com/api/oauth/usage`\n\n) 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.", "url": "https://wpnews.pro/news/show-hn-a-macos-menu-bar-app-showing-claude-subscription-usage", "canonical_source": "https://github.com/palamim/usagent", "published_at": "2026-08-14 11:00:51+00:00", "updated_at": "2026-08-14 11:13:01.064285+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools"], "entities": ["usagent", "Anthropic", "Claude Code", "macOS Keychain", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/show-hn-a-macos-menu-bar-app-showing-claude-subscription-usage", "markdown": "https://wpnews.pro/news/show-hn-a-macos-menu-bar-app-showing-claude-subscription-usage.md", "text": "https://wpnews.pro/news/show-hn-a-macos-menu-bar-app-showing-claude-subscription-usage.txt", "jsonld": "https://wpnews.pro/news/show-hn-a-macos-menu-bar-app-showing-claude-subscription-usage.jsonld"}}