HAL9000
dde71cf8e2
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Successful in 1m12s
CI / quality (pull_request) Successful in 1m24s
CI / push-validation (pull_request) Successful in 33s
CI / helm (pull_request) Successful in 34s
CI / typecheck (pull_request) Successful in 1m33s
CI / build (pull_request) Successful in 1m13s
CI / benchmark-regression (pull_request) Failing after 37s
CI / security (pull_request) Successful in 2m25s
CI / e2e_tests (pull_request) Successful in 4m31s
CI / unit_tests (pull_request) Successful in 6m25s
CI / integration_tests (pull_request) Successful in 6m24s
CI / docker (pull_request) Successful in 1m36s
CI / coverage (pull_request) Successful in 13m7s
CI / coverage (push) Blocked by required conditions
CI / docker (push) Blocked by required conditions
CI / status-check (push) Blocked by required conditions
CI / benchmark-publish (push) Waiting to run
CI / benchmark-regression (push) Waiting to run
CI / status-check (pull_request) Successful in 5s
CI / push-validation (push) Successful in 31s
CI / quality (push) Successful in 1m22s
CI / lint (push) Successful in 1m28s
CI / helm (push) Successful in 43s
CI / build (push) Successful in 1m0s
CI / security (push) Successful in 1m41s
CI / typecheck (push) Successful in 2m5s
CI / e2e_tests (push) Successful in 4m13s
CI / integration_tests (push) Successful in 4m37s
CI / unit_tests (push) Has been cancelled
Split docs/advanced-concepts.md (554 lines) into four sub-documents under docs/advanced-concepts/ and docs/tui.md (634 lines) into four sub-documents under docs/tui/, each under the 500-line limit per CONTRIBUTING.md. Advanced Concepts sub-documents: - docs/advanced-concepts/index.md: Overview, context strategies, LLM backends - docs/advanced-concepts/resource-types.md: Resource types, A2A rename - docs/advanced-concepts/container-tools.md: Container tools, scope chain, budgets, safety - docs/advanced-concepts/e2e-tests-and-plugins.md: E2E tests, code review, plugins TUI sub-documents: - docs/tui/index.md: Overview, getting started, main screen layout - docs/tui/sidebar-and-personas.md: Sidebar states, persona system - docs/tui/input-and-sessions.md: Reference/command input, session management - docs/tui/configuration-and-integration.md: Config, key bindings, theme, integration Updated mkdocs.yml navigation to reflect new sub-document structure. Updated CONTRIBUTORS.md with contribution entry for PR #9903. ISSUES CLOSED: #10533
167 lines
9.1 KiB
Markdown
167 lines
9.1 KiB
Markdown
# 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*
|