freemo
e7df15d453
Implement UI data-provider interface backed by local services. Add Textual-based TUI with plan list, plan detail, diff viewer, and validation summary panes. Add Web UI stub with local-only read-only routes. Configure auto-refresh and manual keybinds. ISSUES CLOSED: #341
3.6 KiB
UI Guide
CleverAgents provides two interface options for monitoring plans, sessions, diffs, and validation results: a Textual-based TUI for terminal use and a read-only Web UI stub that serves JSON endpoints locally.
Both interfaces consume the same UIDataProvider protocol, so the data
displayed is identical regardless of which interface is used.
TUI Dashboard
Launching
agents ui tui
Optional flags:
| Flag | Description |
|---|---|
--project-id, -p |
Project ID to display (default: empty — show all) |
--refresh, -r |
Auto-refresh interval in seconds (overrides tui_refresh_interval setting) |
Layout
The TUI is organized into four panes:
| Pane | Position | Content |
|---|---|---|
| Plan List | Top-left | Table of plans with ID, name, status, created date |
| Plan Detail | Top-right | Full detail of the selected plan including decisions and linked resources |
| Diff Viewer | Bottom-left | Changeset diffs for the selected plan |
| Validation Summary | Bottom-right | Pass/fail validation results |
Keybindings
| Key | Action |
|---|---|
q |
Quit the TUI |
r |
Manual refresh all panes |
1 |
Focus the plan list pane |
2 |
Focus the plan detail pane |
3 |
Focus the diff viewer pane |
4 |
Focus the validation summary pane |
Auto-Refresh
The TUI polls the data provider at a configurable interval. The default is 5 seconds. Override with:
- CLI flag:
--refresh 10 - Environment variable:
CLEVERAGENTS_TUI_REFRESH_INTERVAL=10 - Configuration setting:
tui_refresh_intervalin the settings file
Web UI
Enabling
The web UI is disabled by default. Enable it with:
export CLEVERAGENTS_WEB_UI_ENABLED=true
Launching
agents ui web
Optional flags:
| Flag | Description |
|---|---|
--host, -h |
Bind address (default: 127.0.0.1 — local only) |
--port |
Listen port (overrides web_ui_port setting, default: 8080) |
Endpoints
All endpoints are read-only (GET only).
| Route | Description |
|---|---|
GET /ui/plans?project_id=... |
JSON array of plan summaries |
GET /ui/plans/{plan_id} |
Plan detail (404 if not found) |
GET /ui/sessions |
JSON array of sessions |
GET /ui/diffs/{plan_id} |
Changeset diffs for a plan |
GET /ui/validations/{plan_id} |
Validation results for a plan |
GET /ui/health |
Health check ({"status": "ok"}) |
Security
The web UI binds to 127.0.0.1 by default. Do not expose it to the
network — it is intended for local development only and has no
authentication or authorization.
Configuration Reference
| Setting | Env Var | Default | Description |
|---|---|---|---|
tui_refresh_interval |
CLEVERAGENTS_TUI_REFRESH_INTERVAL |
5 |
Auto-refresh interval in seconds |
web_ui_enabled |
CLEVERAGENTS_WEB_UI_ENABLED |
false |
Enable the web UI server |
web_ui_port |
CLEVERAGENTS_WEB_UI_PORT |
8080 |
Web UI listen port |
Data Provider Architecture
Both the TUI and web UI consume the UIDataProvider protocol defined in
cleveragents.ui.data_provider. The default implementation,
LocalUIDataProvider, resolves services from the DI container.
The protocol exposes these methods:
get_plans(project_id)— plan summariesget_plan_detail(plan_id)— full plan detailget_sessions()— session listget_validations(plan_id)— validation resultsget_diffs(plan_id)— changeset diffsget_logs(plan_id, level)— log entries
Custom providers can be injected for testing or alternative data sources.