Widgets

Widgets are declarative, validated UI primitives over authorized read and action ports (ADR-038), not the top-level product category (ADR-042). A YAML spec declares typed reads, bindings, and registered action ports; the same render tree can be consumed by the CLI/TUI, the Widget Host, and (as it matures) Cortxt OS apps. Nothing in a widget spec can supply arbitrary HTML, CSS, or JS, no widget can expand its own authority or run raw commands, and mutations require explicit confirmation (ADR-038).

The product hierarchy is:

Widget primitive
→ focused View
→ coherent App
→ optional saved app composition

Widget Maker (below) is the current development surface for building and testing individual widget specs. Studio — a coherent product surface for composing prompt-generated views and apps — is the accepted product direction under ADR-042/ADR-041, not yet shipped as a named product; do not expect Studio commands or files before that work lands. The underlying single-widget building blocks are merged to main: cortxt widget generate/edit/remove/reset create, revise, and remove one installed widget spec at a time from a prompt (verified, available today). Declarative, mechanical multi-widget composition also ships today via cortxt widget compose (see below) given a hand-written or scripted composition.yaml. What is not yet built is Studio’s prompt-generated composition of views and apps.

Try it live

The widgets below render live from the same fixture artifacts the landing page uses. Each pairs the widget with the exact CLI command that produces it.

Widget render

Session Agents

Live agent workstreams, execution state swimlanes, and active subagent telemetry.

live

CLI / TUI stream

$ cortxt widget --view session-agents

Loading widget...

Widget render

Usage & Cost

Token consumption, model breakdown, and cost trajectory over time.

live

CLI / TUI stream

$ cortxt widget --view usage-cost

Loading widget...

Widget render

Session Pulse

Real-time orchestrator heartbeat, active run count, and dispatch activity feed.

live

CLI / TUI stream

$ cortxt widget --view session-pulse

Loading widget...

CLI to widget parity

CLI command	Widget	Spec
cortxt widget --view candidates --repo OWNER/REPO	Candidates	widget_contract/specs/candidates-0.1.yaml
cortxt widget --view session-pulse	Session Pulse	widget_contract/specs/session-pulse-0.1.yaml
cortxt widget --view session-agents	Session Agents	widget_contract/specs/session-agents-0.1.yaml
cortxt widget --view usage-cost	Usage and Cost	widget_contract/specs/usage-cost-0.1.yaml
cortxt widget --view docker-status	Docker Status	widget_contract/specs/docker-status-0.1.yaml
cortxt widget --view webhooks --repo OWNER/REPO	Webhooks	widget_contract/specs/webhooks-0.1.yaml
cortxt widget compose --spec composition.yaml --widgets-dir <dir>	Warroom (composed)	any widget + layout

TUI mode

Every view above also renders as colorized terminal text via --tui:

cortxt widget --view session-agents --tui

TUI colors are generated from the same tokens.json shared with the browser widgets and Widget Maker. On a 24-bit-capable terminal (Windows Terminal, iTerm2, modern emulators) you can derive colors directly from the token hex values:

cortxt widget --view session-agents --tui --tui-truecolor

Build your own warroom

Open /widgets/ for the interactive Gallery, Spec Studio, Tokens editor, and the Warroom Compose view. Compose picks widgets from the gallery, arranges them on a grid, generates a composition.yaml, and gives you the CLI command to materialize it:

cortxt widget compose --spec warroom.yaml --widgets-dir agent-platform/widget/specs --snapshot agent-platform/widget/composed.json

Composition is strictly typed per ADR-038: widgets are referenced by exact version, connections are typed, and capabilities never widen. The maker is a static, backend-less tool; the CLI step validates authoritatively.

Design tokens

Widgets, the maker, and the CLI TUI all read tokens.json. Edit colors, elevation, glow, and motion once in the Tokens tab of the maker, and every surface - browser, maker, terminal - updates together.