codex monitor widget
The Kasmos monitor is an Apps SDK widget served by the Kasmos MCP server. Call open_monitor in Codex Desktop to watch live orchestration state without leaving the conversation.
The display mode controls how much detail it renders:
pipis a compact, pinnable picture-in-picture rail with lifecycle progress, running-agent count, and blocker or readiness status.inlineshows the lifecycle, task selector, active task progress, and blocker summary in the conversation.fullscreenadds agents, branches, readiness, the complete wave breakdown, and the event stream for deeper inspection.sidebarfits the complete monitor into a persistent, narrow host pane.
non-apps-sdk hosts should implement the versioned monitor host contract.
prerequisites
The monitor requires all of the following:
kas serveor thekasmosdbuser service running- the
integrations/codexplugin installed - Codex MCP-app rendering enabled
Codex Apps integration is stable and enabled by default. No feature flag is normally required. If Apps were explicitly disabled in ~/.codex/config.toml, re-enable the canonical setting:
[features]
apps = true
On a Codex build without MCP-app rendering, open_monitor returns a text snapshot instead of a widget. That fallback is expected, not a bug.
browser preview
The supported way to see the real widget today is the browser preview. With kas serve running, generate it and open the resulting file in a browser:
kas monitor widget --out preview.html
In multi-project mode, seed the preview with the target project and optional focused task:
kas monitor widget --out preview.html --project kasmos --task codex-live-monitor-ui
When kas serve uses a non-default port or origin, pass the same base URL while generating the preview:
kas serve --port 8080
kas monitor widget --out preview.html --serve-url http://127.0.0.1:8080
The generated file polls a dedicated read-only preview bridge under the configured --serve-url (default: http://127.0.0.1:7433/v1/widget-preview/open-monitor). That bridge accepts only the project and task inputs used to build an open_monitor snapshot. It does not expose the shared MCP server or any mutating tool. The full MCP listener remains unavailable to file:// and other cross-origin callers.
authority boundary
The widget is read-only. open_monitor renders the widget, while the app-only refresh_monitor data tool supplies subsequent snapshots without attaching another output template. Both descriptors explicitly mark the tools read-only, non-destructive, idempotent, and closed-world. The widget cannot call any mutating Kasmos tool. Its action buttons do not invoke lifecycle transitions or mutate Kasmos state; each sends a follow-up message into the conversation instead.
This keeps the coordinate-kasmos approval gate in authority. The coordinating agent must still obtain the required approval before implement_start, merges, pushes, or destructive operations. Users can verify this boundary by observing that a widget action creates a chat request for the agent rather than directly changing task state.
polling and transport
the apps sdk widget polls through window.openai.callTool("refresh_monitor", …). the host-agnostic bundle calls the injected host's refresh method instead. expanded pip, fullscreen, and sidebar panes poll every 2 seconds; expanded inline widgets poll every 3 seconds. host-reported pane visibility slows collapsed panes to 15 seconds and pauses hidden panes, independently of the containing window's visibility. polls are single-flight, failures back off to 30 seconds, and the server uses a one-second ttl cache to avoid repeating snapshot assembly for rapid calls. see the monitor host contract for the cadence and host responsibilities.
Task state and the event feed come from the same database selected by kas serve --db, including custom database paths, so the widget never mixes task and audit history from different stores.
The Codex-hosted widget makes no HTTP, WebSocket, or other network calls of its own. Codex rewrites http:// and ws:// CSP entries to their secure forms, which prevents a sandboxed widget iframe from fetching a localhost Kasmos server. Sending hosted widget data over the MCP bridge avoids that failure mode. The standalone browser preview is the exception: its host shim calls the narrowly scoped read-only preview endpoint described above.