Interactive TUI

PraisonAI CLI provides a rich interactive terminal user interface (TUI) for seamless AI-assisted coding sessions. Inspired by Gemini CLI, Codex CLI, and Claude Code, it offers real token streaming, built-in tools, and a clean terminal experience.

Overview

The Interactive TUI provides:

Real token streaming - Model deltas rendered as they arrive, real time-to-first-token
Built-in tools - File operations, shell commands, web search
Slash commands - /help, /model, /stats, /compact, /undo, /queue, /git-status, /map, and more
@file mentions - Include file content with @file.txt syntax
Shell escape - !cmd runs a shell command inline (gated by PRAISONAI_ALLOW_SHELL); !!cmd also attaches the output as context for the next prompt. See Shell Escape.
Message queuing - Queue messages while agent is processing
Model switching - Change models on-the-fly with /model
Token tracking - Monitor usage and costs with /stats
Context compression - Compact chat_history with /compact (auto-runs at the turn boundary)
Undo/revert - roll files + conversation back with /undo (last turn) and /revert [n] (last n turns) — on by default
Queue management - View and manage queued messages with /queue
Profiling - Measure response times with /profile
Tool status indicators - See when tools are being used
Clean UX - No cluttered panels, just streaming text

Streaming

The interactive CLI consumes real token streaming from agent.iter_stream() — every chunk you see is a live model delta, rendered as it arrives, giving you real time-to-first-token instead of a finished string replayed word-by-word.

If a provider does not support streaming, the CLI transparently falls back to a single non-streamed agent.chat() response — the answer still arrives, just as one block. No configuration required.

For interactive coding, prefer a provider whose OpenAI-compatible endpoint streams (openai, anthropic, gemini, most LiteLLM providers) — you will see real time-to-first-token. See Streaming for the SDK-level API and provider coverage.

Verbose Mode Order

In verbose mode the Q: / A: header prints on the first streamed delta, the body streams in live, and the completion line renders only after the streamed body finishes:

Q: what is 2+2

A: 4

─── Task #1 completed (0.8s, 1 words) ───

The completion line never appears before the answer, and no leading word-replay precedes the streamed body.

Multi-step (tool-using) turns

When a turn uses tools, each LLM step in the loop streams its narrative into the same live assistant message as it completes — you see the model’s reasoning between tool calls appear immediately, instead of waiting for the whole turn to finish.

The primary TUI consumes the existing llm_content display callback that the core (praisonaiagents/llm/llm.py) emits per LLM step — no new API surface, no configuration.

The live message becomes the finalised turn — no duplicate assistant message is appended, so /undo, /revert, and conversation history behave exactly as before. Read-only review turns keep their single-summary behaviour (spinner-only during work) and do not stream intermediate narrative.

Quick Start

# Start interactive mode
praisonai chat

# Or use short flag
praisonai -i

# With a specific model
praisonai chat --llm gpt-4o

Chat Mode (Non-Interactive Testing)

For testing and scripting, use --chat (or praisonai chat) to run a single prompt with interactive-style output:

# Single prompt with tools, streaming output, no boxes
praisonai "list files in current folder" --chat

# Test web search
praisonai "search the web for AI news" --chat

# Test file operations
praisonai "read the file README.md" --chat

--chat is different from praisonai chat which starts a web-based Chainlit UI. The praisonai chat flag is an alias for backward compatibility.

Built-in Tools

Interactive mode comes with 13 built-in tools across 3 groups:

ACP Tools (Agentic Change Plan)

Tool	Description
`acp_create_file`	Create a file with plan/approve/apply/verify flow
`acp_edit_file`	Edit a file with tracking
`acp_delete_file`	Delete a file (requires approval)
`acp_execute_command`	Execute shell commands with tracking

LSP Tools (Code Intelligence)

Tool	Description
`lsp_list_symbols`	List functions, classes, methods in a file
`lsp_find_definition`	Find where a symbol is defined
`lsp_find_references`	Find all references to a symbol
`lsp_get_diagnostics`	Get errors and warnings

Basic Tools

Tool	Description
`read_file`	Read contents of a file
`write_file`	Write content to a file
`list_files`	List files in a directory
`execute_command`	Run shell commands
`internet_search`	Search the web for information

# List available tools
❯ /tools
Available tools: 13
  • acp_create_file, acp_edit_file, acp_delete_file, acp_execute_command
  • lsp_list_symbols, lsp_find_definition, lsp_find_references, lsp_get_diagnostics
  • read_file, write_file, list_files, execute_command, internet_search

Launching with a resumed session

As of PR #4912, you can jump straight back into the interactive TUI with a prior session already restored — no need to launch cold and type /continue:

# Resume most recent project session
praisonai -c

# Resume a specific session id
praisonai --session abc12345

# Branch it non-destructively
praisonai --fork --session abc12345

On launch, the TUI:

Resolves the target session id via the same ProjectSessionStore / find_last_session / session_exists_anywhere path that run --continue / run --session uses.
Restores the recorded session model so the resumed launch continues on the original provider, not the current default.
Replays the prior transcript into scrollback using the same renderer as the in-TUI /continue command.
Wires the primary agent to the resumed session’s store — a follow-up prompt is answered with the restored conversation context, not just after redisplaying it.

If any of this fails, the launch degrades to a fresh session rather than aborting. The no-flag path (praisonai) is byte-identical to previous versions.

Automatic session persistence

As of PR #4943, every interactive conversation is auto-saved from the first turn — no --auto-save flag required. Each completed turn is written to the UnifiedSessionStore, so /sessions lists it and /continue can resume it, even on a fresh install where you have never passed a save flag before. A first-ever session can now become a session to resume. This applies to both interactive paths: the rich prompt_toolkit TUI and the plain-terminal fallback (used when prompt_toolkit is unavailable). Previously the default interactive path never wrote to the store, so /sessions always answered No saved sessions found. and /continue had nothing to continue.

# First launch — no flags needed
praisonai
> Hello, help me refactor foo.py
> /quit

# Later, from any terminal
praisonai
> /sessions          # now lists the previous conversation
> /continue          # resumes it

The --auto-save flag is still relevant for non-interactive praisonai "<prompt>" runs. The interactive TUI persists by default and ignores the flag.

Slash Commands

Command	Description
`/help`	Show available commands
`/exit` or `/quit`	Exit interactive mode
`/clear`	Clear the screen and the agent’s conversation memory (resets both, not just the screen)
`/new`	Start a new conversation — resets both the screen and the agent’s conversation history
`/import <file>`	Import a conversation from a file and restore it into the agent’s state (not just the screen)
`/continue [id]`	Continue the most recent session, or a specific session id when given. Same renderer + agent wiring as the launch flags.
`/tools`	List available tools
`/profile`	Toggle profiling (show timing breakdown)
`/model [name]`	Show or change current model
`/stats`	Show session statistics (tokens, cost) — alias `/cost`, same renderer
`/export [file]`	Export the conversation to a file
`/status`	Show ACP/LSP runtime status
`/auto`	Toggle autonomy mode (auto-delegate complex tasks)
`/debug`	Toggle debug logging to `~/.praisonai/async_tui_debug.log`
`/plan <task>`	Create a step-by-step plan for a task
`/handoff <type> <task>`	Delegate to specialized agent (code/research/review/docs)
`/compact`	Compact the model’s `chat_history` (reports tokens/messages freed); auto-runs at the turn boundary
`/compact-display` (alias `/dense`)	Toggle compact output display mode
`/undo`	Undo last turn (files + history when checkpointing on)
`/revert [n]`	Revert the last N turns (files + conversation)
`/diff`	Show file changes this session (requires `checkpoints.auto`)
`/git-status`	Show working-tree status (operator command)
`/git-diff [--staged]`	Show the uncommitted diff (operator command)
`/git-log [n]`	Show the last `n` commits, default 10 (operator command)
`/git-commit [message]`	Stage and commit; message auto-generated when omitted (operator command)
`/git-undo`	Undo the last commit, keeping changes in the tree (operator command)
`/map [path]`	Show the repository map (operator command)
`/branch [title]`	Fork the current conversation here and switch onto the fork; parent stays resumable
`/branch --at N`	Fork from N user turns back
`/session`	Show current session info, including `Forked from:` / `Forks:` lineage when set
`/queue`	Show queued messages
`/queue clear`	Clear message queue
`/files`	List workspace files for @ mentions

As of PR #4943, /clear, /new, /import, and /continue all round-trip through the agent, not just the screen. They share the same persist + rebuild path, so after any of them the model’s conversation memory matches what you see. Previously /clear / /new cleared only the transcript while the agent kept the pre-clear context, and /import printed Imported N messages but answered as if none had been loaded.

❯ /help

Commands:
  /help          - Show this help
  /exit          - Exit interactive mode
  /clear         - Clear screen
  /continue [id] - Continue most recent session, or a specific session id
  /tools         - List available tools
  /profile       - Toggle profiling (show timing breakdown)
  /model [name]  - Show or change current model
  /stats         - Show session statistics (tokens, cost)
  /compact       - Compact chat_history (auto-runs at the turn boundary too)
  /compact-display - Toggle compact output display (alias /dense)
  /undo          - Undo last turn (files + history when checkpointing on)
  /diff          - Show file changes this session (needs checkpoints.auto)
  /git-status    - Show working-tree status
  /git-diff      - Show the uncommitted diff
  /git-log [n]   - Show recent commits
  /git-commit [m]- Stage and commit (message auto-generated when omitted)
  /git-undo      - Undo the last commit (keeps changes staged)
  /map [path]    - Show the repository map
  /queue         - Show queued messages
  /queue clear   - Clear message queue

@ Mentions:
  @file.txt      - Include file content in prompt
  @src/          - Include directory listing

Features:
  • File operations (read, write, list)
  • Shell command execution
  • Web search
  • Context compression for long sessions
  • Queue messages while agent is processing

@File Mentions

Include file content directly in your prompts using @ syntax, inspired by Gemini CLI and Claude Code. @file and @dir mentions submit through the same expansion path as the legacy REPL — the file’s contents are inlined before the prompt reaches the model on every surface.

# Include a file in your prompt
❯ what does @README.md say about installation?
📄 Included: README.md (2,345 chars)

The README.md file explains that installation can be done via pip...

# Include multiple files
❯ compare @file1.py and @file2.py
📄 Included: file1.py (500 chars)
📄 Included: file2.py (450 chars)

Here are the key differences between the two files...

# Include directory listing
❯ what files are in @src/
📁 Listed: src/ (15 items)

The src/ directory contains the following files...

Files larger than 50KB are automatically truncated
Hidden files and common ignore patterns (node_modules, pycache) are filtered from directory listings
Paths can be relative or absolute
Use ~ for home directory (e.g., @~/Documents/file.txt)

Shell Escape

Run a shell command inline with the ! prefix — no model turn is spent. !!cmd also attaches the output as context for your next prompt.

❯ !git status              # run inline, no model turn
❯ !!git diff               # attach output as context for the next message
❯ summarise the change     # this turn sees the diff

Gated by PRAISONAI_ALLOW_SHELL (default off). See Shell Escape for configuration, safety limits, and failure behaviour.

Model Switching

Change models on-the-fly without restarting:

# Show current model
❯ /model
Current model: gpt-4o-mini

Available models (examples):
  • gpt-4o, gpt-4o-mini
  • claude-3-5-sonnet, claude-3-haiku
  • gemini-2.0-flash, gemini-1.5-pro

Usage: /model <model-name>

# Change to a different model
❯ /model gpt-4o
✓ Model changed: gpt-4o-mini → gpt-4o

# Verify the change
❯ /model
Current model: gpt-4o

Session Statistics

Track token usage and estimated costs:

❯ /stats

Session Statistics
  Model:          gpt-4o-mini
  Requests:       5
  Input tokens:   1,234
  Output tokens:  2,567
  Total tokens:   3,801
  Estimated cost: $0.0023
  History turns:  10

Use /stats regularly to monitor your token usage and avoid unexpected costs.

/stats and /cost are the same output in the async TUI — one renderer, two names. Both are also available in the legacy REPL and praisonai chat, so the command works whichever surface you’re on.

Context Compression

When conversations get long, use /compact to compact the model’s chat_history:

❯ /compact
Compacted context: 240,483 → 94,191 tokens (120 → 47 messages)

/compact:

Compacts the model’s own chat_history, not just the transcript pane.
Reports the tokens and messages it freed.
Runs automatically at the turn boundary when the session nears its context budget, so a long turn no longer waits for the provider to reject the request.

/compact used to be a display toggle. That behaviour moved to /compact-display (alias /dense). See Compaction.

Undo Support

Made a mistake? Use /undo to remove the last conversation turn:

❯ write a function to sort a list
[AI generates sorting function]

❯ /undo
✓ Undone last turn
Removed: write a function to sort a list...

❯ /stats
Session Statistics
  ...
  History turns:  8  # Reduced from 10

/undo rolls the workspace and the conversation back to the previous turn boundary. Checkpointing is on by default in the async TUI — opt out with checkpoints.auto: false or PRAISONAI_CHECKPOINTS=off. The TUI captures a session-start baseline on launch and a pre-turn checkpoint before every submission, so /undo unwinds one turn at a time:

❯ /undo
Undo: Workspace restored to `a1b2c3d` (turn 3: refactor auth handler).

If checkpointing is off, /undo prints an enable hint; if no turns are recorded yet it prints Undo: No checkpoints yet — nothing to undo. See Checkpoints for config-precedence details.

Revert N turns

Use /revert [n] to roll files + conversation back by more than one turn at a time:

❯ /revert 3
Reverted 3 turn(s) — files + conversation restored to a1b2c3d.

A diff preview is shown first. /revert refuses to run beyond the recorded turn count:

❯ /revert 9
Can only revert 1..N turn(s).

Diff

Been editing files for a while and want to see what changed? Type /diff to see workspace file changes since session start.

/diff              # all changes since session start
/diff --turn       # only the last turn's changes (alias: -t)
/diff src/auth.py  # changes to a single file since session start

/diff uses the session-start baseline captured on launch, so it includes edits from earlier turns. It requires auto-checkpointing. When checkpointing is off it prints, verbatim:

Workspace checkpointing is disabled, so /diff has no session baseline to compare against.

Enable it with `checkpoints.auto: true` in config or `PRAISONAI_CHECKPOINTS=on`.

Message Queue

Queue messages while the AI agent is processing. Type new prompts and they’ll be executed in order as each task completes.

# While agent is processing, type more messages
❯ Create a Python function to calculate fibonacci
[Agent processing...]

❯ Add docstrings to the function
❯ Create unit tests

# Check the queue
❯ /queue
⏳ Processing...

Queued Messages (2):
  0. ↳ Add docstrings to the function
  1. ↳ Create unit tests

Use /queue clear to clear, /queue remove N to remove

Queue Commands

Command	Description
`/queue`	Show all queued messages
`/queue clear`	Clear the entire queue
`/queue remove N`	Remove message at index N

Messages are processed in FIFO order (First In, First Out). The agent automatically processes the next queued message when the current task completes.

Message Queue

See the full Message Queue documentation for programmatic usage and API reference.

Interrupting a Turn

Press Ctrl-C while the agent is thinking and the current turn stops at the next step boundary — the partial output is kept, the warm agent stays loaded, and the session is intact. Type the next prompt immediately.

What happens

Each turn runs in a worker thread wired to an InterruptController — the same cooperative-cancellation primitive the core chat loop already checks at every step boundary. Ctrl-C requests the interrupt on the main thread; the worker observes it at the next check and returns.

❯ summarise the whole repo
  ⏳ Praison AI is thinking... (Ctrl-C to interrupt)
^C
  ⏹ Interrupting… (finishing current step)
Turn interrupted by user.

❯ ok, just the README instead

One press vs. two

Press	State	Behaviour
`Ctrl-C` × 1	Turn running	Cooperative cancel. Prints `⏹ Interrupting…`; the core loop stops at the next step boundary; partial output is kept; a `system` message `Turn interrupted by user.` is appended to the transcript. Warm agent and session survive.
`Ctrl-C` × 2	Turn still running (blocked in a slow tool call that hasn’t checked yet)	The wrapper stops waiting on the worker thread. The cancellation request is still set — the daemon worker observes it whenever it next reaches a check-point. Control returns to the prompt immediately.
`Ctrl-C` × 1	Idle (no turn running, prompt-toolkit path)	Resets the current input line — unchanged from before.

While a cancel is in flight

If you press Ctrl-C twice and try to start a new turn before the previous one has observed the cancel, the CLI refuses cleanly rather than double-booking the shared controller:

❯ new question
  ⏹ Previous turn is still cancelling; please wait a moment and try again.

This is deliberate — silently starting a new turn would either un-cancel the abandoned worker (and let it resume against the warm session) or race two turns against the same agent. Wait a moment and retry.

Between turns, a stale Ctrl-C you pressed while nothing was running does not kill the next turn — the interrupt is cleared at the start of every fresh turn. You only cancel what is actually running.

Cooperative means the loop stops at the next boundary — it does not kill the current step. A single long-running blocking call (a slow HTTP request, a long shell command) finishes before the interrupt is observed. That is why a second Ctrl-C is available: it stops waiting on the wrapper side and returns you to the prompt.

Cancelling a turn does not cost you the session. Re-run praisonai chat in the same directory, or use praisonai session resume <id>, and the transcript up to (and including) the partial output is restored.

Profiling

Enable profiling to see timing breakdown:

❯ /profile
Profiling enabled

❯ what is 2+2
4

─── Profiling ───
Import:      0.1ms
Agent setup: 0.3ms
LLM call:    1,234.5ms
Display:     15.2ms
Total:       1,250.1ms

❯ /profile
Profiling disabled

Output Comparison

Interactive Mode (Clean)

❯ what is 2+2

4

Regular Mode (Verbose)

╭─ Agent Info ─────────────────────────────────────────────╮
│  👤 Agent: DirectAgent                                   │
│  Role: Assistant                                         │
╰──────────────────────────────────────────────────────────╯
╭──────────────────────── Task ────────────────────────────╮
│ what is 2+2                                              │
╰──────────────────────────────────────────────────────────╯
╭─────────────────────── Response ─────────────────────────╮
│ 4                                                        │
╰──────────────────────────────────────────────────────────╯

Features

Streaming Responses

Responses stream token-by-token as real model deltas from agent.iter_stream(), similar to Gemini CLI and Claude Code. When a provider cannot stream, the CLI falls back to a single agent.chat() call and prints the completed answer as one block. Tool-using turns also stream each LLM step’s narrative live into one assistant message — see Multi-step (tool-using) turns and the Streaming section above.

Tool Status Indicators

When tools are used, you’ll see status indicators:

❯ list files in current folder
⚙ Using list_files...
✓ list_files complete

Here are the files in the current folder:
- README.md
- main.py
- config.yaml

Security

High-risk tools require approval:

write_file - HIGH risk level
execute_command - CRITICAL risk level

❯ run the command 'rm -rf /'
╭─ 🔒 Tool Approval Required ──────────────────────────────╮
│ Function: execute_command                                │
│ Risk Level: CRITICAL                                     │
╰──────────────────────────────────────────────────────────╯

Rejecting a tool call takes an optional one-line reason that flows back to the agent as the tool’s result. See Reject with a Reason.

Python API

Basic Usage

from praisonai.cli.features import InteractiveTUIHandler

# Create handler
handler = InteractiveTUIHandler()

# Define callbacks
def on_input(text):
    """Handle regular input."""
    return f"You said: {text}"

def on_command(cmd):
    """Handle slash commands."""
    if cmd == "/exit":
        return {"type": "exit"}
    return {"type": "command", "message": f"Executed: {cmd}"}

# Initialize and run
session = handler.initialize(
    on_input=on_input,
    on_command=on_command
)

handler.run()

Configuration

from praisonai.cli.features.interactive_tui import (
    InteractiveConfig,
    InteractiveTUIHandler
)

config = InteractiveConfig(
    prompt="🤖 >>> ",           # Custom prompt
    multiline=True,             # Enable multi-line input
    history_file="~/.praisonai_history",  # Persistent history
    max_history=1000,           # Max history entries
    enable_completions=True,    # Enable auto-complete
    enable_syntax_highlighting=True,  # Enable highlighting
    vi_mode=False,              # Use emacs keybindings
    auto_suggest=True,          # Show suggestions
    show_status_bar=True,       # Show status bar
    color_scheme="monokai"      # Color theme
)

handler = InteractiveTUIHandler()
session = handler.initialize(config=config)

Custom Completions

from praisonai.cli.features.interactive_tui import InteractiveSession

session = InteractiveSession()

# Add slash commands for completion
# Note: Autocomplete only triggers when you type /
session.add_commands(["help", "exit", "cost", "model", "plan", "queue"])

# Add symbols from your codebase
session.add_symbols(["MyClass", "my_function", "CONFIG"])

# Refresh file completions
session.refresh_files(root=Path("/path/to/project"))

History Management

from praisonai.cli.features.interactive_tui import HistoryManager

# Create history manager
history = HistoryManager(
    history_file="~/.my_history",
    max_entries=500
)

# Add entries
history.add("first command")
history.add("second command")

# Navigate
prev = history.get_previous()  # "second command"
prev = history.get_previous()  # "first command"
next_cmd = history.get_next()  # "second command"

# Search
results = history.search("/help")  # Find commands starting with "/help"

# Clear
history.clear()

Status Display

from praisonai.cli.features.interactive_tui import StatusDisplay

display = StatusDisplay(show_status_bar=True)

# Set status items
display.set_status("model", "gpt-4o")
display.set_status("tokens", "1,234")
display.set_status("cost", "$0.05")

# Print formatted output
display.print_welcome(version="1.0.0")
display.print_response("Here's the solution...", title="AI Response")
display.print_error("Something went wrong")
display.print_info("Processing...")
display.print_success("Done!")

Keyboard Shortcuts

Shortcut	Action
`↑` / `↓`	Navigate history
`Ctrl+R`	Search history
`Ctrl+A`	Move to start of line
`Ctrl+E`	Move to end of line
`Ctrl+W`	Delete word backward

Editing

Shortcut	Action
`Tab`	Auto-complete
`Ctrl+C` (turn running)	Cancel the running turn cooperatively — keeps partial output and warm agent. Press twice to stop waiting on a stuck step. See details.
`Ctrl+C` (idle)	Clear the current input line.
`Ctrl+D`	Exit (on empty line)
`Ctrl+L`	Clear screen

Multi-line

Shortcut	Action
`Enter`	New line (in multi-line mode)
`Enter` on empty	Submit input
`Ctrl+Enter`	Submit immediately

VI Mode

Enable VI keybindings:

config = InteractiveConfig(vi_mode=True)

VI mode shortcuts:

Esc - Enter command mode
i - Insert mode
a - Append mode
dd - Delete line
/ - Search

Customization

Custom Prompt

config = InteractiveConfig(
    prompt="🤖 praisonai> "
)

Dynamic Prompt

def get_prompt():
    branch = get_git_branch()
    return f"({branch}) >>> "

# Update prompt dynamically
session.config.prompt = get_prompt()

Custom Theme

from prompt_toolkit.styles import Style

custom_style = Style.from_dict({
    'prompt': '#00aa00 bold',
    'input': '#ffffff',
    'completion': 'bg:#333333 #ffffff',
})

# Apply to session
session._prompt_session.style = custom_style

Integration

With Slash Commands

from praisonai.cli.features import (
    InteractiveTUIHandler,
    SlashCommandHandler
)

# Create handlers
tui = InteractiveTUIHandler()
slash = SlashCommandHandler()

def on_command(cmd):
    if slash.is_command(cmd):
        return slash.execute(cmd)
    return None

session = tui.initialize(on_command=on_command)

With Cost Tracking

from praisonai.cli.features import (
    InteractiveTUIHandler,
    CostTrackerHandler
)

tui = InteractiveTUIHandler()
cost = CostTrackerHandler()
cost.initialize()

def on_input(text):
    # Process with AI...
    response = ai.chat(text)
    
    # Track costs
    cost.track_request("gpt-4o", input_tokens, output_tokens)
    
    # Update status
    tui._session.display.set_status("cost", f"${cost.get_cost():.4f}")
    
    return response

session = tui.initialize(on_input=on_input)

Fallback Mode

If prompt_toolkit is not available, a simple fallback is used:

# Without prompt_toolkit
>>> (Enter empty line to submit)
Hello, help me with my code

# Basic input still works, just without advanced features

Best Practices

Use @file mentions - Include relevant files directly in prompts for context
Monitor with /stats - Check token usage regularly to avoid surprises
Use /compact - Compress history when conversations get long
Switch models - Use /model gpt-4o-mini for simple tasks, /model gpt-4o for complex ones
Enable profiling - Use /profile to identify slow operations
Use completions - Press Tab often for faster input
Learn shortcuts - Ctrl+R for history search is powerful

Feature Comparison

PraisonAI Interactive Mode compared to other AI CLI tools:

Feature	PraisonAI	Claude Code	Gemini CLI	Codex CLI
`/help`	✅	✅	✅	✅
`/clear`	✅	✅	✅	✅
`/tools`	✅	✅	✅	✅
`/model`	✅	✅	✅	✅
`/stats`	✅	✅	✅	✅
`/compact`	✅	✅	✅	✅
`/undo`	✅	✅	✅	✅
`/revert [n]`	✅
`/queue`	✅	✅	✅	✅
`@file` mentions	✅	✅	✅	✅
Message queuing	✅	✅	✅	✅
Autocomplete	✅	✅	✅	✅
Profiling	✅	❌	✅	❌
Real token streaming	✅	✅	✅	✅
Tool execution	✅	✅	✅	✅

Troubleshooting

Completions Not Working

# Install prompt_toolkit
pip install prompt_toolkit

# Verify installation
python -c "import prompt_toolkit; print(prompt_toolkit.__version__)"

History Not Persisting

# Ensure history file path is writable
config = InteractiveConfig(
    history_file=os.path.expanduser("~/.praisonai_history")
)

Display Issues

# Set terminal type
export TERM=xterm-256color

# Or disable colors
config = InteractiveConfig(enable_syntax_highlighting=False)

@File Mentions Not Working

# Ensure the file exists and is readable
ls -la @yourfile.txt

# Use absolute paths if relative paths don't work
❯ what does @/full/path/to/file.txt say?

# Check for typos in the path
❯ what does @README.md say?  # Correct
❯ what does @readme.md say?  # Case-sensitive on Linux/Mac

Testing Interactive Mode

PraisonAI provides a CSV-driven test runner for testing interactive mode functionality. This is useful for:

Validating tool execution (ACP/LSP tools)
Testing multi-step workflows
Automated regression testing
CI/CD integration

Running Interactive Tests

# Run built-in smoke tests
praisonai test interactive --suite smoke

# Run tool-specific tests
praisonai test interactive --suite tools

# Run refactoring workflow tests
praisonai test interactive --suite refactor

# Run multi-agent tests
praisonai test interactive --suite multi_agent

# List available suites
praisonai test interactive --list

# Run custom CSV tests
praisonai test interactive --csv my_tests.csv

# Keep artifacts for debugging
praisonai test interactive --suite tools --keep-artifacts

# Generate CSV template
praisonai test interactive --generate-template

CSV Test Format

Tests are defined in CSV format with the following columns:

Column	Required	Description
`id`	Yes	Unique test identifier
`name`	Yes	Test name
`prompts`	Yes	Single prompt or JSON array for multi-step
`expected_tools`	No	Comma-separated tools that must be called
`forbidden_tools`	No	Comma-separated tools that must NOT be called
`expected_files`	No	JSON dict of `{path: content_regex}`
`expected_response`	No	Regex pattern for response
`judge_rubric`	No	LLM judge evaluation rubric
`judge_threshold`	No	Pass threshold (default: 7.0)
`skip_if`	No	Skip condition (e.g., `no_openai_key`)
`agents`	No	JSON array for multi-agent tests

Example CSV:

id,name,prompts,expected_tools,expected_files,judge_rubric
test_01,Create File,"Create hello.py with print('hello')",acp_create_file,"{""hello.py"": ""print.*hello""}",File created successfully
test_02,Multi-step,"[""Create test.py"", ""Edit test.py""]","acp_create_file,acp_edit_file",,Files modified correctly

Test Artifacts

When running with --keep-artifacts, each test generates:

transcript.txt - Full conversation
tool_trace.jsonl - Structured tool call trace
result.json - Test result with assertions
workspace/ - Snapshot of workspace files
judge_result.json - LLM judge evaluation (if rubric provided)

CLI Options

praisonai test interactive [OPTIONS]

Options:
  --csv, -c PATH          Path to CSV test file
  --suite, -s NAME        Built-in suite: smoke, tools, refactor, multi_agent, github-advanced
  --model, -m MODEL       LLM model for agent (default: gpt-4o-mini)
  --judge-model MODEL     LLM model for judge (default: gpt-4o-mini)
  --workspace, -w PATH    Workspace directory
  --artifacts-dir PATH    Directory for artifacts
  --fail-fast, -x         Stop on first failure
  --keep-artifacts        Keep test artifacts
  --no-judge              Skip judge evaluation
  --verbose, -v           Verbose output
  --list                  List available suites
  --generate-template     Generate CSV template

GitHub Advanced Tests

The github-advanced suite provides 5 end-to-end GitHub workflow scenarios that exercise real GitHub operations:

Scenario	Description
GH_01	Repo Lifecycle + Feature + Issue + Fix + PR
GH_02	CI Regression + Workflow Fix + PR
GH_03	Refactor + Performance Micro-Optimization
GH_04	Documentation + Broken Link Fix
GH_05	Multi-Agent Collaboration

Prerequisites:

gh CLI installed and authenticated
PRAISON_LIVE_NETWORK=1 environment variable

# Run GitHub Advanced tests
PRAISON_LIVE_NETWORK=1 praisonai test interactive --suite github-advanced

# Check prerequisites
gh auth status

Artifacts Generated:

RUNBOOK.md - Step-by-step execution log
gh_repo_view.json - Repository state
gh_issue_list.json - Issues created
gh_pr_list.json - Pull requests created
transcript.txt - Full conversation
tool_trace.jsonl - Tool call trace
verifications.json - Verification results

Message Queue - Queue messages while agent is processing
Slash Commands - Full slash command reference
Cost Tracking - Detailed cost monitoring
Session - Session management
Session Forking - Fork mid-session with /branch
Mentions - @file mention syntax
Git Integration - Git workflow support

​Interactive TUI

​Overview

​Streaming

​Verbose Mode Order

​Multi-step (tool-using) turns

​Quick Start

​Chat Mode (Non-Interactive Testing)

​Built-in Tools

​ACP Tools (Agentic Change Plan)

​LSP Tools (Code Intelligence)

​Basic Tools

​Launching with a resumed session

​Automatic session persistence

​Slash Commands

​@File Mentions

​Shell Escape

​Model Switching

​Session Statistics

​Context Compression

​Undo Support

​Revert N turns

​Diff

​Message Queue

​Queue Commands

Message Queue

​Interrupting a Turn

​What happens

​One press vs. two

​While a cancel is in flight

​Profiling

​Output Comparison

​Interactive Mode (Clean)

​Regular Mode (Verbose)

​Features

​Streaming Responses

​Tool Status Indicators

​Security

​Python API

​Basic Usage

​Configuration

​Custom Completions

​History Management

​Status Display

​Keyboard Shortcuts

​Navigation

​Editing

​Multi-line

​VI Mode

​Customization

​Custom Prompt

​Dynamic Prompt

​Custom Theme

​Integration

​With Slash Commands

​With Cost Tracking

​Fallback Mode

​Best Practices

​Feature Comparison

​Troubleshooting

​Completions Not Working

​History Not Persisting

​Display Issues

​@File Mentions Not Working

​Testing Interactive Mode

​Running Interactive Tests

​CSV Test Format

​Test Artifacts

​CLI Options

​GitHub Advanced Tests

​Related Features

Interactive TUI

Overview

Streaming

Verbose Mode Order

Multi-step (tool-using) turns

Quick Start

Chat Mode (Non-Interactive Testing)

Built-in Tools

ACP Tools (Agentic Change Plan)

LSP Tools (Code Intelligence)

Basic Tools

Launching with a resumed session

Automatic session persistence

Slash Commands

@File Mentions

Shell Escape

Model Switching

Session Statistics

Context Compression

Undo Support

Revert N turns

Diff

Message Queue

Queue Commands

Interrupting a Turn

What happens

One press vs. two

While a cancel is in flight

Profiling

Output Comparison

Interactive Mode (Clean)

Regular Mode (Verbose)

Features

Streaming Responses

Tool Status Indicators

Security

Python API

Basic Usage

Configuration

Custom Completions

History Management

Status Display

Keyboard Shortcuts

Navigation

Editing

Multi-line

VI Mode

Customization

Custom Prompt

Dynamic Prompt

Custom Theme

Integration

With Slash Commands

With Cost Tracking

Fallback Mode

Best Practices

Feature Comparison

Troubleshooting

Completions Not Working

History Not Persisting

Display Issues

@File Mentions Not Working

Testing Interactive Mode

Running Interactive Tests

CSV Test Format

Test Artifacts

CLI Options

GitHub Advanced Tests

Related Features