Praison AI

TUI Overview

Interactive Terminal User Interface for PraisonAI

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

python
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.

Diagram

Input

Agent

Output

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

  1. Launch the TUI
    bash
    praisonai tui launch
  2. Launch with options
    bash
    praisonai tui launch --model gpt-4 --workspace ./my-project

Installation

TUI is included by default with PraisonAI:

bash
pip install praisonai

For a minimal installation without TUI:

bash
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

WidgetDescription
ChatWidgetDisplays chat history with streaming support
ComposerWidgetInput area with slash command detection
StatusWidgetStatus bar showing session, model, tokens, cost
QueuePanelWidgetQueue display with cancel/retry actions
ToolPanelWidgetTool execution status and approvals

Screens

ScreenDescription
MainScreenPrimary chat interface
QueueScreenQueue management
SettingsScreenConfiguration
SessionScreenSession browser

Keyboard Shortcuts

KeyAction
Ctrl+EnterSend message
Ctrl+CCancel current run
Ctrl+QQuit TUI
Ctrl+LClear screen
F1Show help
F2Toggle queue panel
F3Open 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.

Related

TUI Commands

CLI commands reference

 Queue System

Queue management details