An interactive terminal UI runs PraisonAI agents with streaming output, queues, and session persistence.

from praisonaiagents import Agent

agent = Agent(name="tui-assistant", instructions="Help via the PraisonAI terminal UI.")
agent.start("Summarise what is in my TUI queue.")

The user runs praisonai tui launch and chats with the agent in a full-screen Textual session.

PraisonAI TUI

The PraisonAI TUI (Terminal User Interface) provides an app-like interactive experience for running AI agents directly in your terminal. Built with Textual, it offers a modern, responsive interface with streaming output, queue management, and session persistence.

Features

Event-loop driven UI - Always-active input, non-blocking operations
Multi-pane layout - Chat history, status bar, queue panel, tool execution
Streaming output - Token-by-token display with backpressure handling
Queue management - Submit multiple tasks, cancel, retry, priority ordering
Session persistence - Resume sessions after crashes
Slash commands - Quick actions like /help, /model, /cost
Keyboard shortcuts - Efficient navigation and control

Quick Start

Launch the TUI

praisonai tui launch

Launch with options

praisonai tui launch --model gpt-4 --workspace ./my-project

Installation

TUI is included by default with PraisonAI:

pip install praisonai

For a minimal installation without TUI:

pip install praisonai[lite]

Architecture

The TUI is built on a clean separation of concerns:

┌─────────────────────────────────────────────────────────┐
│                    TUI Application                       │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│  │  App    │ │ Widgets │ │ Screens │ │ Events  │       │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘       │
│       └───────────┴───────────┴───────────┘             │
│                         │                               │
│  ┌─────────────────────┴─────────────────────┐         │
│  │         Event Bus / Message Queue          │         │
│  └─────────────────────┬─────────────────────┘         │
│                         │                               │
│  ┌─────────┐ ┌─────────┴─────────┐ ┌─────────┐         │
│  │ Queue   │ │ Worker Pool       │ │ Persist │         │
│  │ Manager │ │ (Agent Runners)   │ │ Layer   │         │
│  └─────────┘ └───────────────────┘ └─────────┘         │
└─────────────────────────────────────────────────────────┘

Key Components

Widgets

Widget	Description
`ChatWidget`	Displays chat history with streaming support
`ComposerWidget`	Input area with slash command detection
`StatusWidget`	Status bar showing session, model, tokens, cost
`QueuePanelWidget`	Queue display with cancel/retry actions
`ToolPanelWidget`	Tool execution status and approvals

Screens

Screen	Description
`MainScreen`	Primary chat interface
`QueueScreen`	Queue management
`SettingsScreen`	Configuration
`SessionScreen`	Session browser

Keyboard Shortcuts

Key	Action
`Ctrl+Enter`	Send message
`Ctrl+C`	Cancel current run
`Ctrl+Q`	Quit TUI
`Ctrl+L`	Clear screen
`F1`	Show help
`F2`	Toggle queue panel
`F3`	Open settings
`/`	Start slash command

Best Practices

Learn keyboard shortcuts early

Ctrl+Enter to send and F2 for the queue panel speed up daily terminal workflows.

Use the queue for long runs

Enqueue heavy tasks instead of blocking the interactive session.

Clear the screen between scenarios

Ctrl+L resets the view when switching test cases or agents.

Pair TUI with simulation in CI

Script headless runs for regression tests; use the interactive TUI for exploration.

TUI Commands

CLI commands reference

Queue System

Queue management details

JSON File Persistence

TUI Commands

​PraisonAI TUI

​Features

​Quick Start

​Installation

​Architecture

​Key Components

​Widgets

​Screens

​Keyboard Shortcuts

​Best Practices

​Related

TUI Commands

Queue System

PraisonAI TUI

Features

Quick Start

Installation

Architecture

Key Components

Widgets

Screens

Keyboard Shortcuts

Best Practices

Related