TUI

TUI

Terminal User Interface for CortexPrism, providing an interactive split-pane chat experience with real-time tool call monitoring and ANSI escape code rendering directly in the terminal.

Architecture

Single file in src/tui/:

File	Purpose
terminal.ts	TerminalUI class — full TUI rendering and input handling

TerminalUI Class

TerminalUI manages a full-screen terminal interface with three panels and raw keyboard input handling.

State Properties

Property	Type	Description
messages	TuiMessage[]	Chat message history
tools	TuiToolCall[]	Active and completed tool calls
input	string	Current input buffer
cursorPos	number	Cursor position within input
focus	"chat" | "tools" | "input"	Active panel
status	string	Status bar text
history	string[]	Command history for up/down navigation
scrollOffset	number	Chat scroll position
cols / rows	number	Terminal dimensions (from Deno.consoleSize())

Data Types

interface TuiMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp?: string;
}

interface TuiToolCall {
  name: string;
  status: 'running' | 'success' | 'error';
  durationMs?: number;
  result?: string;
}

Layout

┌─────────────────────────────────────────────────┐
│  Cortex — TUI                  (title bar)       │
├──────────────────────┬──────────────────────────┤
│                      │ ✓ tool_name (150ms)      │
│  You: hello          │ … another_tool            │
│  Bot: Hi! How can... │ ✗ failed_tool             │
│                      │                          │
│  (chat panel, 70%)   │ (tools panel, 30%)       │
│                      │                          │
│                      │                          │
├──────────────────────┴──────────────────────────┤
│ > user input here▍                              │
├─────────────────────────────────────────────────┤
│ [idle] | Messages: 12 | Tools: 3 | Ctrl+C...    │
└─────────────────────────────────────────────────┘

• Title bar: Row 0, inverted
• Chat panel: Rows 1 to inputRow - 1, left 70% of width
• Tools panel: Rows 1 to inputRow - 1, right 30% of width
• Input bar: Row rows - 2, inverted, shows > <input> with cursor
• Status bar: Row rows - 1, inverted, shows status and stats

Tool Call Display

Status	Icon	Display
running	…	… tool_name
success	✓	✓ tool_name (150ms)
error	✗	✗ tool_name

API Methods

Method	Description
addMessage(msg)	Append a chat message and re-render
updateLastMessage(content)	Append text to the most recent message (for streaming)
addToolCall(tool)	Register a new tool call
updateToolCall(name, updates)	Update the latest tool call with given name
setStatus(status)	Update status bar text
setOnSend(cb)	Register send callback (Enter key)
setOnCancel(cb)	Register cancel callback (Ctrl+C)
start()	Enter raw mode, begin input loop, render initial frame
stop()	Exit raw mode, clear screen

Input Handling

Key	ASCII	Action
Enter	13	Send message if input non-empty; adds to history
Backspace	127	Delete character before cursor
Ctrl+C	3	Trigger cancel callback
Ctrl+L	12	Clear chat and tools panels
Up arrow	ESC[ A	Navigate command history backward
Down arrow	ESC[ B	Navigate command history forward
Right arrow	ESC[ C	Move cursor right
Left arrow	ESC[ D	Move cursor left
Printable	32–126	Insert character at cursor position

Rendering

render() uses ANSI escape sequences:

• \x1b[2J\x1b[H — Clear screen and move to home
• \x1b[<row>;<col>H — Absolute cursor positioning
• \x1b[7m / \x1b[0m — Invert / reset for title and status bars

Messages wrap to the chat panel width. Tool calls are listed in insertion order.

CLI

cortex tui          # Start interactive TUI

See Also

• Workflow Engine — DAG workflows with step callbacks
• Triggers — Event-driven triggers that can produce TUI messages
• Eval System — Evaluation with TUI result display