macOS menu-bar app + pinned usage side-panel

Goal

On macOS, turn jacked's existing system-tray into a real menu-bar app: a live, glanceable pill in the menu bar (worst account's 5-hour · weekly %, color-coded), a click-down dropdown showing every account's two windows, and an optional side panel pinned to the right edge of the screen that stays visible on every Space — so the user never has to hunt for a browser tab to see usage. The dropdown and panel render the same usage bars as the dashboard (colored fill = quota used, white time-marker = position in the window), so a user can see at a glance when an account is burning faster than the clock.

Acceptance Criteria

Each is a done-condition Phase 6 verifies against the running app.

• On macOS, starting the jacked service shows a menu-bar item whose title is live text reflecting the worst account's 5h · 7d %, color-coded (green <71, amber 71–90, red >90), refreshing on an interval — with no browser open.
• Clicking the menu-bar item opens a dropdown showing every account's 5-hour and weekly windows as the dashboard's bars, each including the white .elapsed-marker at the time-elapsed position, plus reset time and color coding.
• Accounts that share an email but differ by organization are grouped under one login header (with a "N orgs" chip and a connecting rail), each org shown as its own sub-row with its own plan badge and meters; the active org is marked.
• A "Toggle Side Panel" action pins a borderless, always-on-top panel to the right screen edge; it is visible across all Spaces and above full-screen apps, does not steal focus, re-pins correctly on display add/remove/resolution change, and toggling again hides it.
• The dropdown and the side panel render the same compact page (one component); their bars match the live dashboard with no divergent rendering logic.
• Menu actions work: Open Dashboard, Toggle Side Panel, Auto-swap (reflects and toggles current state), Add account (launches the existing OAuth flow), Restart, Quit (cleanly stops uvicorn — no orphaned process, no stuck port).
• The menu-bar agent does not start its own server: it health-checks and connects to the existing ServiceRunner/LaunchAgent-managed uvicorn on 127.0.0.1:8321, and shows a clear degraded state if the server is down.
• Non-macOS platforms keep the existing pystray tray with no behavioral change.
• rumps and the required pyobjc frameworks are darwin-only dependencies; a Windows/Linux install resolves and runs unaffected.
• The side panel uses a purpose-built compact dark-glass theme (not a shrunken dashboard page) and reuses the existing usage bar component verbatim.
• uv run python -m pytest passes, including new unit tests for the worst-account summary, the account-grouping util, the /panel route, and the platform branch selection.

Non-Goals / Out of Scope

The scope-creep firewall. This feature explicitly does NOT:

Key Decision: reuse the web bars, native shell around them

The rich bars (5h/7d fill, white time-marker, multi-org grouping) render in a WKWebView that loads a new compact page reusing the dashboard's renderUsageBar() — not redrawn in native AppKit. The window/menu-bar behavior (status-item live text, always-on-top, all-Spaces, edge-pinning, non-activating) is done natively in PyObjC.

This was chosen on merit, not ease: native redraw would feel marginally crisper and could use true NSVisualEffectView vibrancy, but it forks the bar/marker/threshold/grouping logic into a second renderer that drifts on every dashboard change (a tech-debt liability), and the truly-native version is a separate Swift app requiring Developer-ID signing + notarization — fragmenting the clean pip/uv install. Reuse keeps one source of truth and one distribution. The single real loss (OS vibrancy) is mitigated by a deliberate compact dark-glass CSS theme; the mockups prove the opaque-dark treatment looks premium. Logic that could drift (e.g. account grouping) is centralized in one shared util so the two surfaces share meaning.

Architecture

One service, platform-appropriate face. The existing ServiceRunner (uvicorn in a daemon thread) is unchanged. On macOS the service launcher starts a new rumps-based agent instead of the pystray Icon; on other platforms it starts pystray exactly as today. The rumps agent owns the status item and, via PyObjC (rumps is PyObjC, so this runs in the same Cocoa run loop), an NSPopover (dropdown) and an NSPanel (side panel), each hosting a WKWebView pointed at a new compact /panel page. A timer polls a lightweight summary endpoint to set the live menu-bar title.

flowchart TB
    subgraph svc["jacked service (one process)"]
      SR["ServiceRunner\nuvicorn @ 127.0.0.1:8321\n(unchanged)"]
      subgraph mac["macOS face (new)"]
        APP["MacMenuBarApp (rumps)\nNSStatusItem + timer"]
        POP["NSPopover + WKWebView\n(dropdown)"]
        PAN["NSPanel + WKWebView\n(pinned side panel)"]
      end
      WIN["pystray Icon\n(Windows/Linux, unchanged)"]
    end
    SR -->|serves| WEB["/panel  (compact page)\nreuses renderUsageBar() + .elapsed-marker\n+ groupAccountsByLogin()"]
    SR -->|serves| API["/api/analytics/usage-overview\n/api summary  (worst account)"]
    APP -->|poll summary| API
    APP -->|live title| TITLE["menu-bar pill\nJ ● 96%·78%"]
    POP -->|loads| WEB
    PAN -->|loads| WEB
    WEB -->|fetch + live update| API
  

flowchart TB
    SR[ServiceRunner uvicorn 8321] --> WEB[/panel compact page]
    SR --> API[/api summary + usage-overview]
    APP[MacMenuBarApp rumps] --> API
    APP --> TITLE[menu-bar pill]
    POP[NSPopover WKWebView] --> WEB
    PAN[NSPanel WKWebView] --> WEB
    WEB --> API
  

Data flow

• Pill: rumps timer → GET summary → compute/read worst account 5h·7d → set NSStatusItem title + color.
• Dropdown / panel: WKWebView loads /panel → fetches account + usage data → renders bars via the shared renderUsageBar() and groupAccountsByLogin(), live-updating like the dashboard.
• Window behavior: panel is .nonactivatingPanel, status-level, collectionBehavior = canJoinAllSpaces | stationary | fullScreenAuxiliary, pinned to NSScreen.visibleFrame right edge, re-pinned on didChangeScreenParametersNotification.

Files & Interfaces

Testing & Verification

• Unit (uv run python -m pytest): worst-account summary computation; groupAccountsByLogin() (single org, shared-email/multi-org, provider mix); platform-branch selects rumps on darwin / pystray elsewhere (mocked sys.platform); /panel returns 200 and includes the bar component.
• CI parity: replicate the full CI workflow locally before pushing (per repo rule), PASS/FAIL per step.
• Phase 6 — prove it runs: /qa on the /panel page (bars + markers + grouping render; live update); manual native check of the menu-bar pill, dropdown, and pinned panel (always-on-top, all-Spaces, non-activating, re-pin on display change, clean Quit). Capture screenshots / output tied to each acceptance criterion.

Open Questions

• Summary endpoint: reuse /api/analytics/usage-overview for the pill, or add a tiny dedicated /api/menubar-summary? (Lean: reuse if it already yields per-account 5h/7d cheaply; otherwise a 1-field endpoint to keep the timer light.) — resolved during planning by reading the endpoint.
• Does the dashboard also adopt groupAccountsByLogin() now (consistency), or only the panel this round? (Lean: ship the shared util, wire the panel; dashboard adoption optional/non-blocking.)
• Default visibility: does the side panel auto-show on first launch, or stay hidden until toggled? (Lean: hidden by default; remember last state.)

jacked spec · feeds superpowers:writing-plans → /dc → subagent execution → /qa → /pr.