cleveragents-core/docs/tui/configuration-and-integration.md

# TUI: Configuration, Key Bindings, Theme & Integration (v3.7.0)

> **Milestone:** v3.7.0 — M8: TUI Implementation
> **Parent:** [TUI Overview](index.md)

---

## Configuration

### Settings Screen

The Settings screen (`F2` or `/settings`) provides a GUI for all TUI configuration:

- **Theme** — select from 17+ Textual built-in themes (default: Dracula)
- **Sidebar width** — configure the visible sidebar width (default: 32 chars)
- **Session persistence** — enable/disable session history persistence
- **Cost display** — configure cost display precision and currency
- **Notification duration** — configure how long Flash notifications stay visible
- **Keybindings** — view all keybindings (editing not yet supported in v3.7.0)

### Configuration File

TUI settings are stored in `~/.config/cleveragents/config.toml` under `[tui]`:

```toml
[tui]
theme = "dracula"
sidebar_width = 32
session_db_path = "~/.local/state/cleveragents/tui.db"
notification_duration = 3.0     # seconds
cost_display_precision = 2      # decimal places
```

TUI state (last persona, sidebar state, window dimensions) is stored separately in
`~/.config/cleveragents/tui-state.yaml`:

```yaml
last_persona: "feature-dev"
last_preset: "think: high"
last_session_id: "01HXM8C2..."
sidebar_state: "visible"
theme_override: null
window_width: 180
window_height: 50
```

---

## Key Bindings

### Global Bindings

| Key | Action |
|-----|--------|
| `ctrl+q` | Quit the TUI |
| `F1` | Open context-sensitive help panel |
| `F2` / `ctrl+,` | Open Settings screen |
| `ctrl+s` | Open Sessions screen |
| `ctrl+n` | New session tab |
| `ctrl+w` | Close current session tab |
| `ctrl+[` | Previous session tab |
| `ctrl+]` | Next session tab |

### Conversation Bindings

| Key | Action |
|-----|--------|
| `alt+up` | Move block cursor up |
| `alt+down` | Move block cursor down |
| `enter` / `space` | Expand/collapse focused block |
| `ctrl+b` | Focus sidebar (when visible) |

### Prompt Bindings

| Key | Action |
|-----|--------|
| `tab` | Cycle to next persona |
| `ctrl+tab` | Cycle to next argument preset |
| `shift+tab` | Cycle sidebar state (hidden → visible → fullscreen) |
| `shift+enter` / `ctrl+j` | Insert newline (multi-line mode) |
| `escape` | Dismiss overlay / exit multi-line mode / navigate toward main screen |

### Sidebar Bindings (when focused)

| Key | Action |
|-----|--------|
| `up` / `down` | Navigate plan/project list |
| `enter` | Open detail modal for selected item |
| `escape` | Return focus to prompt |

---

## Theme and Styling

The TUI uses Textual's CSS (TCSS) system with semantic color tokens. The default theme is
**Dracula**. All 17+ Textual built-in themes are supported and switchable via:

```bash
/theme dracula        # Switch to Dracula theme
/theme nord           # Switch to Nord theme
/theme monokai        # Switch to Monokai theme
/theme                # Show current theme
```

Or via the Settings screen (`F2`).

### Throbber

A rainbow gradient animated bar spans the full width of the screen at the top, visible only
when the actor is processing. The gradient cycles through a 12-color spectrum at 15fps.
When idle, the throbber row collapses to zero height.

### Notification System

The Flash bar (height: 1, above the prompt) displays transient notifications:

- **Info** — blue, 3 seconds
- **Warning** — yellow, 5 seconds
- **Error** — red, 10 seconds (or until dismissed with `escape`)
- **Success** — green, 3 seconds

---

## TuiMaterializer — Output Rendering Integration

The `TuiMaterializer` bridges the existing `OutputSession` / `ElementHandle` pipeline
(ADR-021) to Textual widgets. All existing CLI command producers render in the TUI without
modification — the same code that renders Rich tables in the CLI renders interactive Textual
widgets in the TUI.

| ElementHandle Type | Textual Widget |
|--------------------|----------------|
| `PanelHandle` | `Static` container with key-value `Label` pairs in a `Collapsible` |
| `TableHandle` | `DataTable` widget |
| `TreeHandle` | `Tree` widget |
| `ProgressHandle` | `ProgressBar` (determinate) or `Throbber` (indeterminate) |
| `StatusHandle` | `Label` with semantic CSS class |
| `CodeHandle` | Read-only `TextArea` with tree-sitter syntax highlighting |
| `DiffHandle` | Custom `DiffView` widget (unified and side-by-side modes) |
| `SeparatorHandle` | `Rule` widget |
| `ActionHintHandle` | `Static` with muted text and command references |

---

## Real-Time A2A Event Subscription

The TUI subscribes to A2A events for real-time visibility into system activity:

| Event | TUI Effect |
|-------|-----------|
| `plan.phase_changed` | Sidebar PlansPanel: update phase indicator |
| `plan.state_changed` | Sidebar PlansPanel: update state badge |
| `plan.decision_made` | Sidebar PlansPanel: update depth counter |
| `tool.invoked` | Conversation: mount ToolCall widget (pending) |
| `tool.completed` | Conversation: update ToolCall widget (done/fail) |
| `validation.completed` | Conversation: append validation result |
| `plan.apply_completed` | Sidebar: update terminal state; Flash: show completion |
| `plan.error` | Flash: show error; Sidebar: mark plan as errored |
| `session.message` | Conversation: stream ActorResponse content |

In local mode, events arrive via RxPY observables. In server mode, events arrive via A2A
`TaskStatusUpdateEvent` / `TaskArtifactUpdateEvent` via SSE.

---

## Content Pruning and Safety Behaviors

### Content Pruning

When the conversation stream exceeds the configurable threshold (default: 500 message blocks),
old messages are automatically collapsed (not deleted) to maintain rendering performance.
Collapsed messages remain in the session history and can be expanded by scrolling up.

Configure the pruning threshold:

```toml
[tui]
conversation_prune_threshold = 500
```

### Safety Behaviors

The TUI enforces safety behaviors from the active persona's safety profile:

- **Shell danger detection** — commands matching destructive patterns are highlighted in red
  with a confirmation overlay before execution
- **Permission questions** — single-file tool operations render an inline `PermissionQuestionWidget`
  in the conversation stream; multi-file operations push the full `PermissionsScreen`
- **Cost warnings** — when session cost approaches the configured budget, a persistent warning
  appears in the Flash bar
- **Loading states** — the throbber and per-block loading indicators prevent user confusion
  during long-running operations

---

## Related ADRs

| ADR | Title | Relevance |
|-----|-------|-----------|
| [ADR-044](../adr/ADR-044-tui-architecture-and-framework.md) | TUI Architecture and Framework | Core TUI design decisions |
| [ADR-021](../adr/ADR-021-cli-and-output-rendering.md) | CLI and Output Rendering | TuiMaterializer integration |
| [ADR-026](../adr/ADR-026-agent-client-protocol.md) | Agent-to-Agent Protocol (A2A) | TUI-to-application communication |

---

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