ratatui ecosystem and provides a multi-modal interface for session management, agent interaction, and real-time run monitoring.
Overview and Architecture
The TUI is encapsulated within thepalyra-cli crate and operates as a standalone interactive mode. It leverages a dedicated OperatorRuntime to manage gRPC communication with the palyrad gateway, handling streaming events and command execution.
Key Components
| Component | File Path | Role |
|---|---|---|
App | crates/palyra-cli/src/tui/mod.rs#122-152 | Central state machine for the TUI, managing transcript, input, and UI mode. |
OperatorRuntime | crates/palyra-cli/src/client/operator.rs#15-17 | Business logic layer for interacting with the Gateway and Control Plane. |
ManagedRunStream | crates/palyra-cli/src/client/operator.rs#31-35 | Wraps the gRPC RunStream, providing an MPSC-based event queue for the TUI loop. |
TuiSlashPaletteState | crates/palyra-cli/src/tui/slash_palette.rs#110-113 | Manages the state of the command palette, including suggestions and active commands. |
Data Flow: Run Stream Processing
The TUI uses an asynchronous run loop that polls for terminal events and drains gRPC stream events concurrently. Sources: crates/palyra-cli/src/tui/mod.rs#177-193, crates/palyra-cli/src/client/operator.rs#137-151Shared Chat Commands & Parity
Palyra maintains strict parity between the Web Console and the TUI using a shared command registry. This registry defines slash commands, their execution context (local vs. server), and surface visibility.Command Registry Implementation
The registry is stored as a JSON artifact in the web application but is compiled into the CLI binary usinginclude_str! and the OnceLock pattern.
- Registry Path: apps/web/src/chat/chatCommandRegistry.json#1-121
- Loading Logic: crates/palyra-cli/src/shared_chat_commands.rs#135-143
- Surface Filtering: Commands are filtered via
SharedChatCommandSurfaceto ensure TUI-only commands like/settingsor/shelldo not appear in the web UI, and vice versa crates/palyra-cli/src/shared_chat_commands.rs#64-68.
Common TUI Commands
| Command | Execution | Description |
|---|---|---|
/agent | Server | Switch active agent or open agent picker apps/web/src/chat/chatCommandRegistry.json#39-49. |
/status | Local | Print compact runtime status in the transcript apps/web/src/chat/chatCommandRegistry.json#15-25. |
/undo | Server | Restore latest safe checkpoint apps/web/src/chat/chatCommandRegistry.json#147-157. |
/shell | Local | Toggle local shell execution capability crates/palyra-cli/tests/shared_chat_command_parity.md#50-50. |
The Slash Palette
The Slash Palette is the primary navigation and discovery mechanism. It provides real-time suggestions based on the user’s input and the currentTuiSlashEntityCatalog.
Entity Catalog and Suggestions
The catalog caches entities retrieved from the daemon to provide instant autocomplete for IDs and keys. Sources: crates/palyra-cli/src/tui/slash_palette.rs#8-16, crates/palyra-cli/src/tui/slash_palette.rs#132-134Implementation Details
- Trigger: Activation occurs when input starts with
/crates/palyra-cli/src/tui/slash_palette.rs#135-139. - Command Resolution: Uses
resolve_shared_chat_command_nameto handle aliases (e.g.,/abortresolving to/interrupt) crates/palyra-cli/src/tui/slash_palette.rs#145-149. - Suggestion Logic: If a command is recognized, it triggers
build_entity_suggestionsto populate the palette with relevant items from theTuiSlashEntityCatalogcrates/palyra-cli/src/tui/slash_palette.rs#171-181.
UI States and Interaction
The TUI utilizes aMode and Focus system to manage keyboard input routing.
UI Modes (enum Mode)
- Chat: The standard interaction mode crates/palyra-cli/src/tui/mod.rs#61-61.
- Picker: Used for full-screen selection of Agents, Sessions, or Models crates/palyra-cli/src/tui/mod.rs#63-63.
- Approval: Intercepts the loop when a
ToolApprovalRequestis received from the stream crates/palyra-cli/src/tui/mod.rs#65-65. - Settings: Overlay for toggling UI features like
show_toolsorshow_thinkingcrates/palyra-cli/src/tui/mod.rs#64-64.
Focus Management
TheFocus enum (crates/palyra-cli/src/tui/mod.rs#54-57) determines whether keystrokes (like arrows) scroll the Transcript or move the cursor in the Input box.
Tool Approvals
When an agent requests a sensitive tool, theManagedRunStream yields a ToolApprovalRequest. The TUI switches to Mode::Approval, prompting the operator. The decision is sent back via send_tool_approval_decision which routes the response through the gRPC request stream crates/palyra-cli/src/client/operator.rs#50-68.
Sources: crates/palyra-cli/src/tui/mod.rs#53-81, crates/palyra-cli/src/client/operator.rs#154-173