UI Guide

KosmoKrator ships with two rendering modes — a full-screen interactive TUI and a lightweight ANSI fallback — so it works everywhere from modern GPU-accelerated terminals to bare SSH sessions. This guide covers how each mode works, what to expect, and how to get the best experience.

Dual Renderer System

At startup KosmoKrator checks whether the Symfony TUI library is available (class_exists(Tui::class)). If the library is installed, it launches in TUI mode. If the library is not present — for example in a minimal installation or inside a basic SSH session — it falls back to ANSI mode, which uses only standard ANSI escape codes and readline for input.

You can override the auto-detection with a CLI flag:

TUI Mode

The TUI is built on Symfony TUI with a Revolt event loop, giving it a responsive, non-blocking architecture that updates the screen in real time while the agent is working.

Editor Widget

The EditorWidget provides a full multi-line input area. Press Shift+Enter to insert a new line without submitting, and Enter to send the message. The editor supports basic cursor movement, selection, and clipboard paste.

Overlay Dialogs

Interactive prompts — permission requests, settings panels, the session picker — appear as overlay dialogs added on top of the conversation. They can be dismissed with Escape and navigated with arrow keys.

Animations & Activity Indicators

While the agent is processing, the TUI shows a live breathing animation and a spinning indicator. Subagent activity is reflected in real time via the SubagentDisplayManager, which refreshes the agent tree overlay as children spawn and complete.

Toast notifications appear briefly for transient events — tool completions, errors, or status changes — and fade away automatically. They provide feedback without interrupting the conversation flow.

Swarm Dashboard

Press Ctrl+A at any time to open the swarm dashboard, an overlay widget that shows every active subagent, its status, elapsed time, and dependency edges. Press Ctrl+A again (or Escape) to dismiss it.

Syntax Highlighting & Markdown

Code blocks in agent responses are syntax-highlighted via tempest/highlight with a custom KosmokratorTerminalTheme that matches the KosmoKrator color palette. Markdown rendering is handled by Symfony TUI's MarkdownWidget with a custom stylesheet tuned for terminal readability.

ANSI Mode

ANSI mode uses pure ANSI escape codes for color and formatting, with PHP's readline extension for line editing and history. It works in literally any terminal — no alternate screen buffer, no event loop, no special capabilities required.

Markdown Formatting

Agent responses are formatted by MarkdownToAnsi, which converts CommonMark AST nodes into ANSI-colored text. Specialized handlers extract tables and nested lists for clean alignment. The markdown parsing itself uses league/commonmark.

Table Rendering

The AnsiTableRenderer produces aligned, bordered tables using box-drawing characters, automatically truncated to the terminal width.

Agent Tree Display

When subagents are active, the ANSI renderer shows a tree of running agents using box-drawing characters (├─, └─) via the shared AgentDisplayFormatter.

Shared Components

Both renderers share a common set of UI components that ensure a consistent look regardless of which mode is active:

Terminal Compatibility

Context Bar

In TUI mode, a context bar at the bottom of the screen displays real-time context window usage. It shows the current token count as a percentage of the configured maximum:

The context bar also shows active tasks as an indented tree — the parent task and any running subagents — so you always know what the agent is working on without opening the full swarm dashboard.

Output Display

Tool results and agent responses are rendered differently depending on the active mode:

TUI Output

• Inline widgets — Tool results appear as collapsible blocks inside the conversation. Press Ctrl+O to toggle collapse/expand.
• Diff highlighting — File edits are rendered as unified diffs with word-level color highlighting via UI/Diff/.
• Code with syntax highlighting — Code blocks use KosmokratorTerminalTheme for consistent colors across all supported languages.
• Markdown — Agent prose is rendered with headers, bold, italic, links, and bullet lists via the custom MarkdownWidget stylesheet.

ANSI Output

• Colored blocks with tool icons — Each tool call is prefixed with its celestial symbol icon from Theme.php and colored to indicate success/failure.
• Truncated to terminal width — All output respects $COLUMNS. Long lines are wrapped or truncated to prevent horizontal scroll.
• Line-by-line streaming — Agent responses stream as they are generated, with ANSI-colored text appearing line by line.

Feature Comparison

Keyboard Shortcuts

The TUI mode supports the following keyboard shortcuts for efficient navigation:

Subagent Rendering

Subagents spawned by the orchestrator use a NullRenderer by default — they produce no terminal output of their own. Results are forwarded to the parent agent and displayed through the parent's renderer. Active subagents appear in the TUI's swarm dashboard (Ctrl+A) or the ANSI agent tree display.