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

---

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]:

[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:

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:

/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:

[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	TUI Architecture and Framework	Core TUI design decisions
ADR-021	CLI and Output Rendering	TuiMaterializer integration
ADR-026	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