Build Context Panel v1 native app and widget

[cbusillo]

Objective

Build Context Panel v1 as a native macOS app plus WidgetKit surface for tracking usage limits across OpenAI, Anthropic, and Google, including multiple logins per provider.

Finish Line

Friend-installable macOS app and widget tracks multi-account AI usage limits

Current Status

State: UX work paused after a live widget/app prototype revealed product-shape issues: the app opens to widget previews instead of a real overview, sidebar selection is confusing, provider account math uses the tightest account instead of pooled interchangeable capacity, and setup is only partly plumbed through a dev JSON config. New recovery issues were created for the reset: #23 app information architecture, #24 pooled provider math, and #25 macOS Settings setup.
Next action: Start with #23 before more UI polish, then apply #24 math so widget/app copy is coherent.
Blocked by: Decision on whether to keep a right inspector or simplify to a two-pane app.
Last verified: 2026-05-07.

Scope

MVP means a friend-installable native macOS prototype that answers the user's immediate question: which account/model has room, when does it reset, and is OpenAI fast mode safe right now?

Included:

• OpenAI/Codex live percent/reset connector from local ~/.code and ~/.codex auth roots.
• Gemini Code Assist live percent/reset connector from Gemini CLI auth roots plus explicitly supplied OAuth client inputs.
• Claude local status connector showing login/subscription metadata and local stats freshness, with live allowance marked unknown.
• Local snapshot persistence and refresh history.
• Native setup/detail app for account labels, auth-root selection, refresh diagnostics, and raw normalized snapshots.
• WidgetKit glance reading cached snapshots only, with no network work in the widget extension.
• OpenAI fast-mode forecast using percent pressure, reset times, local burn history, and a configurable safety reserve.
• Repeatable local build and friend-facing README instructions.

Excluded for MVP:

• Mac App Store/TestFlight distribution.
• Automatic Claude personal subscription allowance detection unless a clean provider signal appears.
• Google Cloud project quota/billing adapters beyond Gemini Code Assist.
• General ChatGPT subscription counters outside the Codex/Fast Mode usage surface.
• Cross-machine sync.

Acceptance Criteria

• App can add and label at least two OpenAI auth roots and one Gemini auth root without exposing secrets in logs, UI debug output, or persisted snapshots.
• App can refresh OpenAI/Codex and Gemini/Code Assist into normalized percent/reset usage snapshots.
• Claude connector displays logged-in/subscription metadata and local stats freshness while marking live allowance unknown.
• Local snapshot history survives app restart and records staleness/error state per provider account.
• Fast-mode forecast can answer safe, safe for about N, save fast mode, or needs calibration for enabled OpenAI accounts.
• Widget shows cached provider/account state, reset timing, and the OpenAI fast-mode recommendation in supported widget sizes.
• Widget tap opens the app detail/setup path.
• Friend-facing build instructions work on a clean Mac with local provider CLIs/auth already configured.
• CI covers connector parsers, snapshot storage, forecast math, and widget/app build targets.

Relationships

• Bootstrap repo PR: Bootstrap Context Panel repo #1.

Validation

• Local: scripts/commit-gate.sh.
• Connector smoke tests: CodexRateLimitProbe, GeminiQuotaProbe, and ClaudeLimitProbe with redacted output only.
• Native UI: run app locally and capture screenshots for setup, detail, empty, stale, and error states.
• Widget UI: verify small/medium/large widget snapshots using cached data and no network calls from the extension.
• Release: produce a local distributable build and install it on a second macOS user/profile or machine before calling MVP friend-ready.
• GitHub: CI and CodeQL green on the MVP PR.

Decisions

• Build native macOS first with SwiftUI and WidgetKit; no web or Docker surface.
• Widget reads cached snapshots only; the app/agent layer performs provider refreshes.
• OpenAI/Codex is the primary MVP value because it answers the fast-mode safety question.
• Gemini Code Assist is in MVP because live percent/reset buckets are now proven.
• Claude personal subscription allowance is shown as unknown in MVP; do not scrape Keychain or token blobs.
• Multiple accounts/auth roots are MVP scope, not a later enhancement.
• Secrets stay local; output and persisted snapshots store only normalized, redacted provider state.

Open Questions

• Should MVP launch as a standard window only, or include a menu bar extra from the start?
• What default reserve buffer should fast-mode forecasting use before saying safe?
• For Gemini, should MVP require users to provide OAuth client values manually, or should it discover them from the installed CLI at runtime without persisting them?
• What is the minimum friend distribution path: unsigned local build, Developer ID signed build, or later notarization?