feat(quota): show Claude plan limits (5h / weekly / weekly per model) in the island

[mutoe]

Problem

Claude Code's /usage shows three rate-limit windows — 5-hour, weekly (all models), weekly (current model) — and they are the thing that actually stops a long session. Nothing in the island tells you how close you are until the CLI refuses to continue. The existing token-usage stats are a different question (how much did I spend), not this one (how much is left before I'm cut off).

Change

An opt-in Show Claude plan limits setting, off by default because it reads the Claude Code login.

Data. The Claude Code OAuth token from Keychain (Claude Code-credentials), with ~/.claude/.credentials.json as fallback, sent to GET /api/oauth/usage with the oauth-2025-04-20 beta header — the same call /usage makes. The response's limits[] (session / weekly_all / weekly_scoped with percent, resets_at, severity, the scoped model's display name) is parsed with a fallback to the legacy five_hour / seven_day shape. The token is only ever read; refreshing it would invalidate the one Claude Code holds, so an expired token surfaces as "run Claude Code once".

The Keychain item is read by running security find-generic-password -s "Claude Code-credentials" -w rather than SecItemCopyMatching. Claude Code writes the item through security, so that binary is on the item's ACL and the read is silent; an in-process read from an ad-hoc-signed build prompts on every rebuild because the designated requirement changes. (The ccusage Raycast extension does the same thing.)

Expanded panel. A footer line with every window: mini bar, percent, reset countdown (↻1h56m / ↻6h06m), coloured by severity, refreshed each minute.

Collapsed island. A chip in the left wing next to the mascot — window label, 9pt ring, percent (Fable ◑58%). If the tool-name display is on and a tool is running, the tool name has priority; the chip stays laid out as an invisible placeholder so the bar doesn't change width when they swap. The chip mode is a picker: off / auto / 5h / weekly / weekly (current model).

Auto mode. A window is pressing when its used share exceeds the elapsed share of the window (ahead of pace) or it is at ≥80%. The 5-hour window takes the chip while pressing; otherwise a weekly window — if either weekly is pressing, the one further ahead of pace, else the one with more used. No weekly reported → 5-hour.

Refresh policy. Event-driven on Stop hooks from local Claude sessions: 15s coalesce, at most one fetch a minute, a trailing fetch for stops that landed during the throttle. A 10-minute tick while the setting is on, a fetch on expand if the snapshot is over a minute old, exponential backoff (60s → 15m) on errors, polling stops entirely on 401/403, and nothing runs while the mascot gate says the machine is asleep. The policy is a pure struct (ClaudeQuotaScheduler) so it's tested without timers.

Collapsed-bar layout fix

Putting a ~67pt chip in the left wing exposed a pre-existing layout flaw on notched screens. The collapsed bar was a flexible row centred on the notch with a Spacer(minLength: notchW) between the wings. That guarantees a gap at least as wide as the notch, not that the gap lines up with the cutout — whichever wing is wider pushes the gap sideways and its tail ends up under the physical notch. Screenshots show those pixels; the display doesn't. A long tool name already did this; the chip made it obvious.

Now each wing reports its ideal content width (rigid via fixedSize, the tool name still truncating at its 120pt cap), the row between them is exactly the notch, and the whole bar is offset by half the wing difference so the gap sits on the cutout. The left wing keeps the classic reserve or its content; the right wing is trimmed to its content (count plus badges) so the bar stays clear of menu-bar icons. Width changes ease in and only shrink back after 5s, so a tool name that comes and goes doesn't make the bar breathe. Non-notch screens keep the flexible row and just add the measured overflow. A geometry test pins the shift (it caught the sign inverted on the first attempt).

Tests

• ClaudeQuotaTests: parse of a real response, legacy fallback, garbage rejection, elapsed/pace maths, auto-mode rules (weekly default, 5h takeover at pace/80%, weekly ranked by pace), fixed modes, countdown formats, severity levels, credential parse, request headers, HTTP status mapping.
• ClaudeQuotaSchedulerTests: coalescing, trailing fetch, remembered stops, backoff cap, rejected token, expand staleness.
• ClaudeQuotaMonitorTests: expand fetch, disabled never fetches, burst coalesces, unauthorized stops polling — with an injected UserDefaults suite so no test touches the real setting (a monitor on standard defaults would make every other test's AppState do real credential reads).
• NotchPanelViewTests: wing slot and notch-shift geometry.

Full suite green locally on macOS 26.4 (arm64): 960 tests, 2 skipped, 0 failures. Verified on a 14" notched display by measuring the rendered bar against NSScreen.auxiliaryTopLeftArea: chip right edge 6pt clear of the cutout, bar extent identical across chip ↔ tool-name swaps, no Keychain prompt on a fresh ad-hoc build.

🤖 Generated with Claude Code