# 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](../adr/ADR-044-tui-architecture-and-framework.md) (TUI Architecture),
> [ADR-045](../adr/ADR-045-tui-persona-system.md) (Persona System),
> [ADR-046](../adr/ADR-046-tui-reference-and-command-system.md) (Reference & Command System)

---

## Overview

The CleverAgents TUI is a full-screen terminal application built with
[Textual](https://textual.textualize.io/) >= 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](index.md) — this page
- [Sidebar States & Persona System](sidebar-and-personas.md)
- [Reference/Command Input & Session Management](input-and-sessions.md)
- [Configuration, Key Bindings, Theme & Integration](configuration-and-integration.md)

### Installation

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

```bash
pip install cleveragents[tui]
```

### Launching the TUI

```bash
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*