Skip to main content

Module: dashboard / widgets

The "one-stop" landing surface — common status widgets at a glance (backend health, recent agent sessions, tasks, feeds, metrics).

Status: implemented — frontend in packages/core/src/modules/dashboard/. The dashboard is no longer a grid panel: it is the default seeded workspace (see ../architecture/windowing.md), a layout of common widget-panes. This module's job is now to (1) contribute its own widgets and (2) provide the command to jump to the Dashboard tab. It has no backend surface — workspace layouts persist through backend/modules/workspace/.

Contributions to the layout shell​

  • Widgets: dashboard.welcome (intro card). Other modules contribute more widgets (clubhouse.account, observability.io).

    The welcome card is the app's only body of in-app guidance and is written as such. It used to be two sentences, one of which was "Press Ctrl+K for the command palette" — wrong on a Mac, wrong for anyone who rebound it, and wrong on the keymap preset that gives mod+k to area.focus:up. It now resolves the live chord through bindingsFor/labelSpec and says so honestly when the palette has no binding at all, and it renders the shared WorkspaceLauncher rather than restating the preset list: a second hand-written copy would be missing whichever workspace was added last. See windowing for the launcher.

    dashboard.backendStatus was retired: a whole center pane rendering one line of health text is the clearest case of a readout becoming a destination because a pane was the only way to show anything. The poll moved to backendHealth (packages/core/src/health.ts — one interval for the whole app, stopped when nothing is listening) and renders in the minibuffer status line. It is silent while healthy: a status line that always says "fine" trains you to stop reading it.

  • Commands: dashboard.open — opens the welcome card (registry.openPanel('dashboard.welcome')).

The widget contract​

A widget is a registry contribution (id, title, React component, optional requiredCapabilities, role, optional icon). Widgets are opened as panes — each in a window, like panels (one level, no separate board). Every widget is openable from the command palette (synthesized pane.open:<id>) and from the Start menu. Capability-gated widgets are filtered by the capability service before they appear there.

Widget data comes from each owning module's own backend routes; the dashboard module knows nothing about other widgets' internals — the same inversion as panels-in-the-shell.

Browser vs desktop​

Widgets behave identically in both layouts. Differences come only from individual widgets' capability requirements:

ConcernBrowserDesktop
Capability-gated widgets (e.g. a local system-metrics widget needing desktop APIs)hidden from the picker, slot shows nothingavailable
Backend-sourced widgets (sessions, tasks, feeds)identicalidentical

A widget that is available in one layout and not the other must come from a requiredCapabilities declaration — never from platform sniffing inside the widget. When adding a capability-gated widget, list it in the table above.

Agent context​

The backend-status widget exposes a getAgentContext() snapshot (reachability plus the app name/version when reachable), so the agent can answer "is the backend up?" without its own tool. See agent tools.