cleveragents-core/docs/tui/index.md

Text User Interface (TUI) — v3.7.0

Milestone: v3.7.0 — M8: TUI Implementation Status: In Progress (~42% complete as of 2026-04-15) Goal: Implement the comprehensive Text User Interface using Textual >= 1.0 and all TUI-dependent features.

Key ADRs: ADR-044 (TUI Architecture), ADR-045 (Persona System), ADR-046 (Reference & Command System)

---

Overview

The CleverAgents TUI is a full-screen terminal application built with Textual >= 1.0. It provides a rich, keyboard-driven interface for interacting with actors, managing plans and projects, and monitoring real-time plan execution — capabilities that are impractical in the stateless CLI.

The TUI is the second Presentation-layer surface in the CleverAgents multi-frontend architecture (CLI, TUI, Web, IDE Plugin, A2A Server). All five surfaces communicate exclusively through the A2A protocol (ADR-026) — the TUI never imports directly from the Domain or Infrastructure layers.

Sub-sections:

• Overview & Main Screen Layout — this page
• Sidebar States & Persona System
• Reference/Command Input & Session Management
• Configuration, Key Bindings, Theme & Integration

Installation

The TUI is an optional extra to keep the base installation lightweight:

pip install cleveragents[tui]

Launching the TUI

agents tui                    # Launch with default persona
agents tui --persona feature-dev   # Launch with a specific persona
agents tui --server https://my-server:8080  # Connect to a remote A2A server

---

Getting Started

First Run

On first launch (no personas configured), the TUI opens to the main chat screen with a centered actor selection overlay:

1. The overlay lists all registered actors discovered from the Actor Registry via A2A
2. Select an actor with arrow keys + enter, or type / to search
3. Selection creates a default persona named "default" with the chosen actor and auto-generated argument presets
4. The overlay dismisses and you can begin chatting immediately

Subsequent Launches

The TUI restores the last active persona and session automatically. Your conversation history, sidebar state, and theme preference are all preserved.

---

Main Screen Layout

The MainScreen is the primary interface. It uses a horizontal layout with the conversation taking available space and the sidebar docked to the right:

┌──────────────────────────────────────────────────────┬──────────────────────┐
│ Throbber (height: 1, full width, visible when busy)  │                      │
│ SessionTabs (height: auto, visible when >= 2 sessions)│                      │
├──────────────────────────────────────────────────────┤  SideBar             │
│                                                      │  (dock: right)       │
│  Conversation                                        │  (width: 32-40)      │
│  (flex: 1fr)                                         │  (max-width: 45%)    │
│                                                      │  ┌────────────────┐  │
│  ┌─ ContentsGrid ─────────────────────────────────┐  │  │ PlansPanel     │  │
│  │ Cursor │ Contents stream                       │  │  │ (collapsible)  │  │
│  │  (1ch) │  - Welcome / UserInput / ActorResponse│  │  │                │  │
│  │        │  - ToolCall / PlanProgress / DiffView │  │  ├────────────────┤  │
│  │        │  - TerminalEmbed / Note / Warning     │  │  │ ProjectsPanel  │  │
│  └────────┴───────────────────────────────────────┘  │  │ (collapsible)  │  │
│                                                      │  │                │  │
│  Flash (notification bar, height: 1)                 │  └────────────────┘  │
│                                                      │                      │
│  ┌─ Prompt ────────────────────────────────────────┐ │                      │
│  │ ReferencePickerOverlay (overlay, triggered by @)│ │                      │
│  │ SlashCommandOverlay (overlay, triggered by /)   │ │                      │
│  │ ┌─ PromptContainer ─────────────────────────┐   │ │                      │
│  │ │ [>] PromptTextArea                        │   │ │                      │
│  │ └───────────────────────────────────────────┘   │ │                      │
│  │ PersonaBar: name | actor | preset | cost        │ │                      │
│  └─────────────────────────────────────────────────┘ │                      │
├──────────────────────────────────────────────────────┴──────────────────────┤
│ Footer: F1 Help | shift+tab Sidebar | tab Persona | ctrl+q Quit             │
└─────────────────────────────────────────────────────────────────────────────┘

Conversation Stream

The conversation displays a chronological stream of typed message blocks:

Block Type	Description	Source
Welcome	ASCII art + first-run instructions	App startup (first message only)
UserInput	Your prompt, rendered as Markdown	User submission
ActorResponse	Streaming Markdown with syntax-highlighted code	Actor response events
ActorThought	Actor reasoning (italic, muted, collapsible)	Actor thinking events
ToolCall	Expandable tool invocation with status and output	Tool execution events
PlanProgress	Grid layout with status icons per step	Plan phase changes
DiffView	Unified or side-by-side diff with syntax highlighting	Tool results with diffs
TerminalEmbed	Bordered terminal output	Shell commands or tool terminal output
ShellResult	Shell command output	User ! shell commands
Note	Semantic info/warning/error notifications	System notifications

The conversation uses a 2-column grid: a 1-character cursor column (left) navigable with alt+up/alt+down, and the content stream (right). Press enter or space on a block to expand/collapse it.

---

Architecture Notes

The TUI is implemented in src/cleveragents/tui/ and follows the layered architecture (ADR-001):

src/cleveragents/tui/
├── app.py                  # CleverAgentsApp root
├── cleveragents.tcss       # Global app styles
├── screens/                # Screen classes and TCSS
│   ├── main.py             # MainScreen
│   ├── sidebar_full.py     # SidebarFullScreen
│   ├── plan_detail.py      # PlanDetailModal
│   ├── project_detail.py   # ProjectDetailModal
│   ├── persona_editor.py   # PersonaEditorModal
│   ├── settings.py         # SettingsScreen
│   ├── sessions.py         # SessionsScreen
│   └── permissions.py      # PermissionsScreen
├── widgets/                # Custom Textual widgets
│   ├── conversation.py     # Conversation stream widgets
│   ├── prompt.py           # Prompt area and overlays
│   ├── sidebar.py          # Sidebar panels
│   └── throbber.py         # Rainbow throbber
├── materializer.py         # TuiMaterializer implementation
├── persona.py              # Persona loading and management
└── session_db.py           # SQLite session persistence

Import-linter rules enforce that src/cleveragents/tui/ imports only from src/cleveragents/cli/output/ (for TuiMaterializer integration) and A2A client interfaces — never from Domain or Infrastructure layers directly.

---

Documentation for v3.7.0 — IN PROGRESS. Features described here reflect the planned scope as of 2026-04-15. Some features may be adjusted as implementation progresses.

Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot