Skip to content

System Tray

Desktop notification-area icon and control panel for the sidecar — its own login item, not a supervised service

Details

The system tray is work-buddy's desktop face for the sidecar: a notification-area icon that shows daemon health at a glance and opens a control panel, so work-buddy is visible and controllable outside the terminal. It is a convenience layer over the sidecar and the dashboard, not a new control plane — it owns no state and reimplements no lifecycle logic.

What it shows and does

  • Icon — the work-buddy mark with a colored status dot: green (running), yellow (starting), red (wedged), grey (stopped), blue (running but busy on a long dispatch job). The dot colors match the dashboard palette. Tooltip carries the same summary text as wbuddy status.
  • Left-click panel — a dashboard-styled popover: the health headline, a per-service list (each service green/red), a "busy on job X" line when the dispatch loop is working, a contextual primary button (Start work-buddy when down, Stop when up) plus Restart, and footer buttons to Open dashboard and jump to the Activity event log. Stop and Restart are destructive (they kill the sidecar, including the MCP gateway an agent talks through), so they require an in-panel confirm.
  • Right-click menu — a minimal fallback (Open dashboard, Start/Stop/Restart, Quit) that guarantees Quit is always reachable even if the panel fails to render.
  • Quit — closes the tray only; the sidecar keeps running.

How it is wired

  • Status comes from reading runtime/sidecar_state.json and classifying it with the same shared helpers the CLI uses (lifecycle.daemon_health for down/booting/up/wedged, lifecycle.dispatch_busy for the busy overlay), so the tray and wbuddy status can never disagree.
  • Actions call the same pure lifecycle.start_sidecar / stop_sidecar functions the wbuddy verbs wrap, in-process on a worker thread.
  • Open dashboard / Activity reuse the Chrome extension's focus_or_create_tab (collectors/chrome_collector) to focus an existing dashboard tab/window (or create one), deep-linking Activity to Settings → Activity, with a plain webbrowser.open fallback when the extension is absent. It targets the local dashboard URL.

Enabling and lifecycle

  • Gated by tray.enabled (config, default off). wbuddy tray enable sets the flag, registers the WB-Tray login item, and starts the tray; wbuddy tray disable reverses all three; wbuddy tray status reports enabled / registered / running; wbuddy tray run is the foreground entry point the login item invokes.
  • The Windows installer offers a default-checked "tray at login" task; the tray extra is installed unconditionally so wbuddy tray enable works later without a download. wbuddy uninstall (and the Windows uninstaller) tears the tray down alongside the sidecar and PATH shim.

Needs the tray extra (uv sync --extra tray, or pip install -e ".[tray]").