feat(desktop): macOS menu bar tray with running agents per project

[giulianoo0]

There is no way to see what your agents are doing without bringing up the app window. I wanted a quick glance from the menu bar.

This adds a tray icon to the desktop app on macOS. Click it and you get a menu with the agents that are currently running, grouped by project. Each project row shows a count and a submenu with the thread titles and their current phase. Below that there are entries for opening the app, Settings, Usage, Pull Requests, Check for Updates and Quit.

How it works:

• New ElectronTray wrapper service and a DesktopTray orchestrator. Both follow the same Effect service pattern as the application menu.
• The menu is built at click time. The tray fetches one shell snapshot from the local backend over HTTP with the desktop bearer token. No polling, no background timers, nothing runs while the menu is closed. If the backend is unreachable the menu falls back to the last good snapshot or shows "Agents unavailable".
• Counting uses the shared projectThreadAwareness predicate, so "running" means the same thing it means for the mobile Live Activity: starting, running, waiting for approval, waiting for input.
• Settings, Usage and Pull Requests reuse the existing desktop:menu-action IPC channel. The renderer handler now also understands open-usage and open-pull-requests.
• Check for Updates shares the app menu handler, tagged with a "tray" reason.
• The icon is the T3 mark rasterized to a macOS template image, so it recolors for light and dark menu bars.

Scope choices, happy to adjust:

• macOS only for now. Windows and Linux trays have different click and menu semantics and deserve their own pass.
• Local environment only. Remote environments need per connection credentials that the main process does not hold.

Tests cover the menu model (grouping, counts, phases, empty and unavailable states) and the tray wrapper. Typecheck and lint are clean for desktop and web.

The icon in the menu bar:

Done with Claude Code (model: Claude Fable 5).

---

Note

Low Risk
Additive desktop UX on macOS with graceful degradation; reuses existing IPC and update flows with no auth or data-model changes.

Overview
Adds a macOS menu bar tray (darwin-only v1) so users can see live agents and open common actions without focusing the main window.

On tray click, the main process fetches a shell snapshot from the local primary backend (2s timeout, cached fallback, no background polling), builds a native menu via trayMenu using the same projectThreadAwareness rules as mobile Live Activity, and pops it through a new ElectronTray / DesktopTray Effect service pair wired at startup. Menu entries reuse dispatchMenuAction, shared handleCheckForUpdatesClick("tray"), and window reveal/quit plumbing.

The web shell AppSidebarLayout now routes open-usage and open-pull-requests from desktop menu IPC. Unit tests cover the tray wrapper and menu model; a design spec documents scope (local env only).

^{Reviewed by Cursor Bugbot for commit 341562b. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add macOS menu bar tray icon with running agents per project

• Introduces ElectronTray in ElectronTray.ts, a scoped service that creates a single Electron tray icon and exposes a popUpMenu operation to show a native context menu.
• Adds DesktopTray in DesktopTray.ts which, on macOS only, wires the tray icon to display a dynamic menu on click: active agents grouped by project plus quick actions (Open, Settings, Usage, Pull Requests, Check for Updates, Quit).
• Builds the agents model in trayMenu.ts from an OrchestrationShellSnapshot, grouping and sorting threads by project and filtering to active phases.
• Extends the renderer in AppSidebarLayout.tsx to handle open-usage and open-pull-requests menu actions by navigating to the corresponding routes.
• Behavioral Change: tray creation and snapshot fetch failures degrade gracefully without crashing startup; the tray is macOS-only.

^{Macroscope summarized 341562b.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3a147916-a6e6-46d2-ba18-56dd6bb4584d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 341562b. Configure here.}

[cursor]

Tray actions no-op before backend ready

Medium Severity

Tray Settings, Usage, and Pull Requests call dispatchMenuAction, which returns immediately when there is no main window and backendReadyRef is false. The tray is created before bootstrap and is meant to work with no windows open, so those entries can silently do nothing during startup or backend restart while Open, Check for Updates, and Quit still respond.

 

^{Reviewed by Cursor Bugbot for commit 341562b. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new macOS menu bar tray feature with ~800 lines of new code, including new Electron services, backend snapshot fetching, and agent-status menus. New features introducing user-facing behavior warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}