Claude Usage Widget

Claude Code's stored sign-in expires every few hours, and only actually using Claude Code renews it. Rather than retrying against a wall all night (an expired token refuses every request identically), the widget stops requesting entirely and watches the Keychain instead. Start a Claude Code session and it picks up the fresh credential on its own.

Because the endpoint refuses it, and says so precisely:

HTTP 403
permission_error: OAuth token does not meet scope requirement user:profile

Claude Code's interactive login requests user:profile user:inference user:sessions:claude; setup-token grants inference only. No amount of regenerating it will add the missing scope. The desktop app is no help either: it keeps a claude.ai web session in an Electron cookie jar, not an OAuth bearer token.

The usage endpoint is rate limited more tightly than it looks. When it answers 429, the widget shows how long the wait is and resumes by itself the moment it ends — clicking Refresh during a long server-directed wait would only deepen it. The backoff is persisted to disk, so quitting and relaunching does not reset it.

/Applications/ClaudeUsageWidget.app/Contents/MacOS/ClaudeUsageWidget --check

Reports which Keychain items it found, whether the credential parsed and when it expires, whether the endpoint answered, and which rings resolved. It honours any active rate-limit wait; pass --force to query anyway (which will probably deepen the wait). If you built from source, the binary is at ./dist/ClaudeUsageWidget.app/Contents/MacOS/ClaudeUsageWidget.

The Mac App Store requires sandboxing, and a sandboxed app cannot read Claude Code's Keychain item or invoke /usr/bin/security — which is every one of this app's data paths. So it ships the way most Mac utilities do: Developer ID + notarization.

The endpoint is unofficial and undocumented. A trimmed, illustrative response:

{
  "five_hour": { "utilization": 30.0, "resets_at": "..." },
  "seven_day": { "utilization": 47.0, "resets_at": "..." },
  "seven_day_omelette": null,
  "limits": [
    {
      "kind": "weekly_scoped",
      "percent": 3,
      "scope": { "model": { "display_name": "Fable" } }
    }
  ]
}

Things worth knowing if you build something similar:

• The limits array is the authoritative source. Each row has a kind (session, weekly_all, weekly_scoped) and, for per-model rows, the model's display name. The widget reads all three rings from it first.
• Top-level per-model keys are internal codenames, not model names. There is no seven_day_fable; a live response carries keys like seven_day_omelette alongside decoys such as cinder_cove and nimbus_quill. An earlier version guessed the mapping and the Fable ring sat at 0% while real usage climbed — which is why limits now wins. The codename lookup survives only as a fallback for responses without limits, and can be pinned with fableWindowKey in config.json.
• null means 0%, not "unavailable". A per-model key that is present but null means the window applies to your account with no usage yet — which is how /usage renders it.
• User-Agent: claude-code/<version> is not optional in practice. Without it you land in an aggressively rate-limited bucket and get persistent 429s.
• There is deliberately no local estimation. An earlier version derived percentages from transcript token counts when the API was unreachable, which meant inventing a denominator — and it once confidently displayed 3704%. The forecast view is the one piece of local arithmetic, it uses only readings the API returned, and it is always drawn dashed and labelled as a projection.
• Backoff is persisted. Keeping it in memory quietly defeats it: a handful of relaunches can turn a short Retry-After into an hour-long one. The last successful response is cached too, so relaunching costs no request.

Sources/ClaudeUsageWidget/
├── main.swift                    entry point; --check and --render-preview
├── App/
│   ├── AppDelegate.swift         wiring, windows, main menu
│   ├── WidgetPanel.swift         borderless, non-activating, resizable NSPanel
│   ├── StatusItemController.swift  menu bar readout and menu
│   ├── Diagnostics.swift         --check
│   └── PreviewRenderer.swift     --render-preview
├── Core/
│   ├── Models.swift              RingMetric, RingDatum, UsageSnapshot
│   ├── Config.swift              settings, persisted as JSON
│   └── UsageHistory.swift        recorded readings and trend projection
├── Data/
│   ├── CredentialStore.swift     reads Claude Code's credential; redaction
│   ├── OAuthUsageProvider.swift  the endpoint and its tolerant decoder
│   └── UsageCoordinator.swift    refresh loop, cache, persisted backoff
└── UI/
    ├── ActivityRingsView.swift   adaptive geometry, overflow laps
    ├── WidgetView.swift          rings, forecast, or the sign-in prompt
    ├── ForecastView.swift        trajectory chart and verdict
    ├── WaitingView.swift         rate-limit countdown
    ├── OnboardingView.swift      sign in → test connection
    └── SettingsView.swift        Appearance · Rings · Connection

Generating the Xcode project

Everyday work needs no Xcode project. But a Swift package opened in Xcode has no Signing & Capabilities tab and no Product ▸ Archive, so for the Organizer flow you need a real App target, generated from project.yml by XcodeGen:

brew install xcodegen && DEVELOPMENT_TEAM=YOURTEAMID xcodegen generate && open ClaudeUsageWidget.xcodeproj

Pass DEVELOPMENT_TEAM rather than setting the team in Xcode's UI — the UI writes it into the generated project, which the next xcodegen generate overwrites. project.yml is the source of truth; the .xcodeproj is git-ignored. Hardened runtime is enabled there (notarization rejects builds without it) and the sandbox is explicitly off, for the reasons in the FAQ.

Signing certificates: the iOS gotcha

Coming from iOS, Apple Distribution is the trap: it reads as the "release" certificate, but it is not accepted for notarized direct distribution. Create a Developer ID Application certificate in Xcode ▸ Settings ▸ Accounts ▸ Manage Certificates ▸ + (paid Apple Developer Program, Account Holder only), then verify:

security find-identity -v -p codesigning | grep "Developer ID Application"

You can confirm the chain before ever archiving:

CODESIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" ./Scripts/build-app.sh && spctl -a -vvv -t install dist/ClaudeUsageWidget.app

A correctly signed but not-yet-notarized app reports rejected with source=Unnotarized Developer ID — the expected result at that stage.

Cutting a release

Store notarization credentials once (needs an app-specific password from appleid.apple.com):

xcrun notarytool store-credentials "ClaudeUsageWidget" --apple-id you@example.com --team-id YOURTEAMID

Then:

./Scripts/release.sh 1.2.0

It signs with the Developer ID certificate, notarizes, staples, builds the drag-to-Applications .dmg (notarized and stapled separately from the app inside it, since Gatekeeper assesses the container you double-click), writes a SHA-256 checksum, and creates the GitHub Release. It fails early on a missing hardened runtime or secure timestamp, and re-runs the Gatekeeper check on a copy tagged with a download quarantine flag — because an app can pass on the machine that built it and still be refused as a download. Useful flags: --no-publish, --draft, and --app PATH to reuse an existing build.

Release notes

Notes are written as the work happens, one line per user-visible change, in ReleaseNotes/Unreleased.md (rules in ReleaseNotes/CLAUDE.md, so an agent working in the repo keeps it current too). release.sh archives them to ReleaseNotes/v<version>.md, publishes them in the release body, resets the scratch file — and refuses to release when it is empty.

App icon and screenshots

./Scripts/make-icon.sh ~/Downloads/your-icon.png

Generates the full ten-size Resources/AppIcon.icns with sips and iconutil (both ship with macOS); a non-square source is padded, not cropped.

./dist/ClaudeUsageWidget.app/Contents/MacOS/ClaudeUsageWidget --render-preview docs/rings.png

Renders the README image offscreen from fixed demo values, without touching the network. --forecast and --waiting render those views instead.