Terminal UI (@ai-sdk-tool/tui)
Relevant source files
The following files were used as context for generating this wiki page:
The Terminal UI (@ai-sdk-tool/tui) package provides terminal-based user interface primitives and a complete interactive loop for building agent-driven sessions. It is built as a wrapper around @mariozechner/pi-tui and is designed to be model-agnostic, receiving an agent and message history as configuration parameters to drive the interaction.
This module is responsible for rendering streaming assistant text, reasoning segments, and tool execution progress. It integrates with @ai-sdk-tool/harness to manage conversation history, compaction, and command dispatching within a terminal environment.
Sources: packages/tui/AGENTS.md:7-12, packages/tui/README.md:1-5
Core Architecture and Loop
The primary entry point for the terminal interface is the createAgentTUI function. This function manages the entire process lifecycle, including handling standard output resizing and signal interrupts (SIGINT). It establishes a persistent loop that accepts user input, processes commands, and manages the agent's streaming response.
The diagram above illustrates the high-level control flow within the TUI session, from initialization to the recurring input/response loop.
Sources: packages/tui/AGENTS.md:16-20, packages/tui/AGENTS.md:131-135, packages/cea/src/entrypoints/main.ts:881-935
Configuration (AgentTUIConfig)
The TUI is highly configurable via the AgentTUIConfig object passed to createAgentTUI.
| Field | Type | Required | Description |
|---|---|---|---|
agent | { stream(...) } | Yes | An agent instance capable of returning an AgentStreamResult. |
messageHistory | CheckpointHistory | Yes | The conversation history instance used for reading and writing messages. |
header | { title, subtitle? } | No | Static or dynamic text displayed at the top of the terminal. |
footer | { text? } | No | Status text displayed below the input area, often used for token usage. |
commands | Command[] | No | List of available slash commands; defaults to all registered commands. |
toolRenderers | ToolRendererMap | No | Custom render functions for specific tool inputs/outputs. |
onSetup | () => void | No | Async hook executed once before the interaction loop begins. |
Sources: packages/tui/AGENTS.md:40-52, packages/tui/README.md:23-35
Specialized Rendering Components
AssistantStreamView
This component is a specialized Container subclass designed to handle the dual-stream nature of modern LLMs. It manages both standard text and reasoning segments, applying distinct ANSI styling (typically dim or italic for reasoning) as tokens arrive.
Sources: packages/tui/AGENTS.md:65-73, packages/tui/README.md:75-88
BaseToolCallView
Renders the lifecycle of a tool call, including its name, the JSON input while streaming, and the eventual output or error. Developers can override how specific tools appear using the ToolRendererMap.
const toolRenderers: ToolRendererMap = {
shell_execute: (view, input) => {
if (view.getError() !== undefined || view.isOutputDenied()) return;
const cmd = (input as { command: string }).command;
view.setRenderedOverride(`$ ${cmd}`);
},
};
Sources: packages/tui/AGENTS.md:81-91, packages/tui/README.md:104-124
Spinner
A braille-frame spinner intended for use in non-TUI contexts (such as standalone CLI scripts). It provides visual feedback for long-running operations. Note: It should not be used inside a live createAgentTUI session, as the TUI manages its own internal loader widgets.
Sources: packages/tui/AGENTS.md:97-105, packages/tui/README.md:138-155
Thematic and Visual Customization
The package provides a colors object and colorize helper for applying ANSI styles. It also supports deep thematic overrides for Markdown rendering and the editor interface.
This class relationship shows how themes are nested within the main TUI configuration to allow granular control over text styling.
Sources: packages/tui/README.md:175-188, packages/cea/src/entrypoints/main.ts:88-120
Usage Conventions and Anti-Patterns
- Dependency Direction: The TUI package must not import from
@ai-sdk-tool/cea. Instead,ceaconsumestuito build its interactive entry points. - Component Ownership: Views like
AssistantStreamViewandBaseToolCallViewmust be explicitly added to the TUI container tree to be rendered. - Process Control:
createAgentTUIassumes control over the terminal session and signal handling; adding external handlers for SIGINT may cause conflicts. - Input Handling: Supports standard terminal interactions, including
Shift+Enterfor newlines,Tabfor autocomplete, andUp/Downfor command history.
Sources: packages/tui/AGENTS.md:129-140, packages/tui/README.md:46-56, AGENTS.md:32-45
Integration with Harness
The TUI relies on @ai-sdk-tool/harness for core logic. It uses the CheckpointHistory to display past messages and the shouldContinueManualToolLoop predicate to determine if the interface should remain in a "waiting" state while tools execute.
Sources: packages/tui/AGENTS.md:13-15, packages/harness/README.md:130-142