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+ktoarea.focus:up. It now resolves the live chord throughbindingsFor/labelSpecand says so honestly when the palette has no binding at all, and it renders the sharedWorkspaceLauncherrather than restating the preset list: a second hand-written copy would be missing whichever workspace was added last. See windowing for the launcher.dashboard.backendStatuswas 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 tobackendHealth(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:
| Concern | Browser | Desktop |
|---|---|---|
| Capability-gated widgets (e.g. a local system-metrics widget needing desktop APIs) | hidden from the picker, slot shows nothing | available |
| Backend-sourced widgets (sessions, tasks, feeds) | identical | identical |
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.