TUI Dashboard

Zeph includes an optional ratatui-based Terminal User Interface that replaces the plain CLI with a rich dashboard showing real-time agent metrics, conversation history, and an always-visible input line.

Enabling

The TUI requires the tui feature flag (disabled by default):

cargo build --release --features tui

Running

# Via CLI argument
zeph --tui

# Via environment variable
ZEPH_TUI=true zeph

# Connect to a remote daemon (requires tui + a2a features)
zeph --connect http://localhost:3000

When using --connect, the TUI renders token-by-token streaming from the remote agent via A2A SSE. See Daemon Mode for the full setup guide.

Layout

+-------------------------------------------------------------+
| Zeph v0.12.0 | Provider: orchestrator | Model: claude-son...|
+----------------------------------------+--------------------+
|                                        | Skills (3/15)      |
|                                        | - setup-guide      |
|                                        | - git-workflow     |
|                                        |                    |
| [user] Can you check my code?         +--------------------+
|                                        | Memory             |
| [zeph] Sure, let me look at            | SQLite: 142 msgs   |
|        the code structure...           | Qdrant: connected  |
|                                       ▲+--------------------+
+----------------------------------------+--------------------+
| You: write a rust function for fibon_                       |
+-------------------------------------------------------------+
| [Insert] | Skills: 3 | Tokens: 4.2k | Qdrant: OK | 2m 15s   |
+-------------------------------------------------------------+

• Chat panel (left 70%): bottom-up message feed with full markdown rendering (bold, italic, code blocks, lists, headings), scrollbar with proportional thumb, and scroll indicators (▲/▼). Mouse wheel scrolling supported
• Side panels (right 30%): skills, memory, resources, and security metrics — hidden on terminals < 80 cols. The security panel replaces the sub-agents panel when recent events exist (see Security Indicators)
• Input line: always visible, supports multiline input via Shift+Enter. Shows [+N queued] badge when messages are pending
• Status bar: mode indicator, skill count, token usage, security indicators, uptime
• Splash screen: colored block-letter “ZEPH” banner on startup

Keybindings

Normal Mode

Insert Mode

Slash-Command Autocomplete

Typing / on an empty input line opens an inline autocomplete dropdown above the input area. The dropdown shows up to 8 matching commands and filters in real time as you type more characters.

The autocomplete reuses the same command registry as the command palette (Ctrl+P). All 51 slash commands are searchable by prefix or keyword.

File Picker

Typing @ in Insert mode opens a fuzzy file search popup above the input area. The picker indexes all project files (respecting .gitignore) and filters them in real time as you type.

All other keys are blocked while the picker is visible.

Command Palette

Press Ctrl+P in Insert mode to open the command palette. The palette provides read-only agent management commands for inspecting runtime state without leaving the TUI.

Available commands:

View commands are read-only. Action commands (session:new, app:quit, app:theme) modify application state. Daemon commands manage the remote connection (see Daemon Mode). The palette supports fuzzy matching on both command IDs and labels.

Confirmation Modal

When a destructive command requires confirmation, a modal overlay appears:

All other keys are blocked while the modal is visible.

Markdown Rendering

Chat messages are rendered with full markdown support via pulldown-cmark:

Clickable Links

Markdown links ([text](url)) are rendered as clickable OSC 8 hyperlinks in supported terminals. The link display text is styled with the link theme (cyan + underline) and the URL is emitted as an OSC 8 escape sequence so the terminal makes it clickable.

Bare URLs (e.g. https://github.com/...) are also detected via regex and rendered as clickable hyperlinks.

Security: only http:// and https:// schemes are allowed for markdown link URLs. Other schemes (javascript:, data:, file:) are silently filtered. URLs are sanitized to strip ASCII control characters before terminal output.

Diff View

When the agent uses write or edit tools, the TUI renders file changes as syntax-highlighted diffs directly in the chat panel. Diffs are computed using the similar crate (line-level) and displayed with visual indicators:

Syntax highlighting (via tree-sitter) is preserved within diff lines for supported languages (Rust, Python, JavaScript, JSON, TOML, Bash).

Compact and Expanded Modes

Diffs default to compact mode, showing a single-line summary (file path with added/removed line counts). Press e to toggle expanded mode, which renders the full line-by-line diff with syntax highlighting and colored backgrounds.

The same e key toggles between compact and expanded for tool output blocks as well.

Thinking Blocks

When using Ollama models that emit reasoning traces (DeepSeek, Qwen), the <think>...</think> segments are rendered in a darker color (DarkGray) to visually separate model reasoning from the final response. Incomplete thinking blocks during streaming are also shown in the darker style.

Conversation History

On startup, the TUI loads the latest conversation from SQLite and displays it in the chat panel. This provides continuity across sessions.

Message Queueing

The TUI input line remains interactive during model inference, allowing you to queue up to 10 messages for sequential processing. This is useful for providing follow-up instructions without waiting for the current response to complete.

Queue Indicator

When messages are pending, a badge appears in the input area:

You: next message here [+3 queued]_

The counter shows how many messages are waiting to be processed. Queued messages are drained automatically after each response completes.

Message Merging

Consecutive messages submitted within 500ms are automatically merged with newline separators. This reduces context fragmentation when you send rapid-fire instructions.

Clearing the Queue

Press Ctrl+K in Insert mode to discard all queued messages. This is useful if you change your mind about pending instructions.

Alternatively, send the /clear-queue command to clear the queue programmatically.

Queue Limits

The queue holds a maximum of 10 messages. When full, new input is silently dropped until the agent drains the queue by processing pending messages.

File Picker

The @ file picker provides fast file reference insertion without leaving the input area. It uses nucleo-matcher (the same fuzzy engine as the Helix editor) for matching and the ignore crate for file discovery.

How It Works

1. Type @ in Insert mode — a popup appears above the input area
2. Continue typing to narrow results (e.g., @main.rs, @src/app)
3. The top 10 matches update on every keystroke
4. Press Enter or Tab to insert the relative file path at the cursor position
5. Press Escape to dismiss without inserting

File Index

The picker walks the project directory on first use and caches the result for 30 seconds. Subsequent @ triggers within the TTL reuse the cached index. The index:

• Respects .gitignore rules via the ignore crate
• Excludes hidden files and directories (dotfiles)
• Caps at 50,000 paths to prevent memory spikes in large repositories

Fuzzy Matching

Matches are scored against the full relative path, so you can search by directory name, file name, or extension. The query src/app matches crates/zeph-tui/src/app.rs as well as src/app/mod.rs.

Responsive Layout

The TUI adapts to terminal width:

Live Metrics

The TUI dashboard displays real-time metrics collected from the agent loop via tokio::sync::watch channel. The render loop polls the watch receiver before every frame. Frames are only emitted when the dirty flag is set (an event was received since the last draw), so the display does not redraw during idle 250 ms ticks with no activity.

Metrics are updated at key instrumentation points in the agent loop:

• After each LLM call (api_calls, latency, prompt tokens)
• After streaming completes (completion tokens)
• After skill matching (active skills, total skills)
• After message persistence (sqlite message count)
• After summarization (summaries count)
• After each tool execution with filter applied (filter metrics)
• After content sanitization, quarantine, or exfiltration guard activation (security events)

Token counts use a chars/4 estimation (sufficient for dashboard display).

Filter Metrics

When the output filter pipeline has processed at least one command, the Resources panel shows:

Filter: 8/10 commands (80% hit rate)
Filter saved: 1240 tok (72%)
Confidence: F/6 P/2 B/0

The filter section only appears when filter_applications > 0 — it is hidden when no commands have been filtered.

Embed Backfill Progress

When semantic memory is enabled and unembedded messages exist from previous sessions, a background backfill task processes them in micro-batches (32 messages, concurrency 4). The Memory panel shows progress during the backfill:

Backfilling embeddings: 128/512 (25%)

The progress indicator disappears once all messages have been embedded. Backfill uses bounded memory — only one micro-batch is held in memory at a time — so it does not spike memory usage regardless of how many messages need processing.

Confidence Levels Explained

Each filter reports how confident it is in the result. The Confidence: F/1 P/0 B/3 line shows cumulative counts across all filtered commands:

Example: Confidence: F/1 P/0 B/3 means 1 command was filtered with Full confidence (e.g. cargo test — 99% savings) and 3 commands fell through to Fallback (e.g. cargo audit, cargo doc, cargo tree — matched the filter pattern but output was passed through as-is).

When multiple filters compose in a pipeline, the worst confidence across stages is propagated. A Full + Partial composition yields Partial.

Security Indicators

The TUI surfaces the untrusted content isolation pipeline activity through three integration points: a status bar badge, a dedicated side panel, and a command palette entry.

Status Bar SEC Badge

When the content isolation pipeline detects injection patterns or blocks exfiltration attempts, a SEC badge appears in the status bar:

[Insert] | Skills: 3 | Tokens: 4.2k | SEC: 2 flags 1 blocked | API: 12 | 5m 30s

The badge is hidden when all security counters are zero.

Security Side Panel

When security events occur within the last 60 seconds, the bottom-right side panel switches from the sub-agents view to a security view. The panel shows all eight security counters and the five most recent events:

+--------------------+
| Security           |
| Sanitizer runs:  14|
| Inj flags:        3|
| Truncations:      1|
| Quarantine calls:  0|
| Quarantine fails:  0|
| Exfil images:      1|
| Exfil URLs:        0|
| Memory guards:     0|
| Recent events:     |
| 14:32 [inj]  web.. |
|   Detected pattern |
| 14:33 [exfil] llm..|
|   1 image blocked  |
+--------------------+

Event categories use color coding:

Each event line shows the local time (HH:MM), the category badge, and the source (e.g., web_scrape, mcp_response, llm_output). A second line shows the event detail.

When no events have occurred in the last 60 seconds, the panel reverts to the sub-agents view. When all counters are zero and no events exist, the panel displays “No security events.”

Security Event History

Use the security:events command palette entry (Ctrl+P then type “security”) to print the full event history to the chat panel. The output includes every event in the ring buffer (up to 100 entries) with its category, source, timestamp, and detail. This is useful for reviewing events that have scrolled out of the side panel’s 5-event window or that occurred more than 60 seconds ago.

Event Ring Buffer

Security events are stored in a FIFO ring buffer (capacity 100) within MetricsSnapshot. When the buffer is full, the oldest event is evicted. Each event records:

Events are emitted by the sanitizer, quarantine, and exfiltration guard subsystems during the agent loop and flow to the TUI via the metrics watch channel.

Plan View

The TUI shows live plan progress in the side panel.

Activating Plan View

Press p in Normal mode (or use plan:toggle from the command palette) to switch the right side panel between the Sub-agents view and the Plan View. The panel switches automatically when a new plan becomes active.

+--------------------+
| Plan: deploy stag… |  ← goal (truncated with …)
| ↻ Preparing env    |  Running  agent-1   12s
| ✓ Build image      |  Done     agent-2   45s
| ✗ Push artifact    |  Failed   agent-2   8s   image push timeout
| · Run smoke tests  |  Pending  —         —
+--------------------+

Status Colors

Panel Header

The panel title shows the plan goal (truncated to fit the panel width with …). A spinner appears in the title when at least one task is in Running status:

| Plan: build and deploy… [↻] |

When no plan is active, the panel shows:

| No active plan              |

Plan Commands in TUI

All /plan commands work in TUI mode via the input line. The command palette (Ctrl+P) provides quick access without typing the full command:

Stale Plan Cleanup

After a plan reaches a terminal state (completed, failed, or cancelled), the Plan View remains visible for 30 seconds so you can review the final status. After 30 seconds the panel automatically reverts to the Sub-agents view. Press p at any time to dismiss it earlier or bring it back.

Requirements

Plan View requires the tui feature flag:

cargo build --release --features tui

SubAgent Sidebar

When sub-agent orchestration is active, the SubAgents panel in the right sidebar shows each running sub-agent, its current status, and allows you to inspect the full execution transcript.

Keybindings

Transcript Viewer

Pressing Enter on a sub-agent entry loads its JSONL execution transcript into the chat panel. The transcript shows all messages exchanged by that sub-agent, including tool calls and intermediate reasoning, rendered with the same markdown and diff highlighting as the main conversation. Press Esc to return to the normal view.

The SubAgents panel is replaced by the Security panel when recent security events exist (< 60 seconds). Press a explicitly to bring the SubAgents panel back when security events are active.

Deferred Model Warmup

When running with Ollama (or an orchestrator with Ollama sub-providers), model warmup is deferred until after the TUI interface renders. This means:

1. The TUI appears immediately — no blank terminal while the model loads into GPU/CPU memory
2. A status indicator (“warming up model…”) appears in the chat panel
3. Warmup runs in the background via a spawned tokio task
4. Once complete, the status updates to “model ready” and the agent loop begins processing

If you send a message before warmup finishes, it is queued and processed automatically once the model is ready.

Note: In non-TUI modes (CLI, Telegram), warmup still runs synchronously before the agent loop starts.

Performance

Dirty-Flag Idle Suppression

The render loop tracks a dirty flag that is set whenever a terminal event or agent event is received. Frames are only redrawn when the flag is set — idle 250 ms ticks with no new input or agent activity are skipped entirely. This eliminates redundant redraws during periods of inactivity and reduces idle CPU usage.

Event Loop Batching

The TUI render loop uses biased tokio::select! to guarantee input events are always processed before agent events. This prevents keyboard input from being starved during fast LLM streaming or parallel tool execution.

Agent events (streaming chunks, tool output, status updates) are drained in a try_recv loop, batching all pending events into a single frame update. This avoids the pathological case where each streaming token triggers a separate redraw.

Render Cache

Syntax highlighting (tree-sitter) and markdown parsing (pulldown-cmark) results are cached per message. The cache key is a content hash, so only messages whose content actually changed are re-rendered. Cache entries are invalidated on:

• Content change (new streaming chunk appended)
• Terminal resize
• View mode toggle (compact/expanded)

This eliminates redundant parsing work that previously re-processed every visible message on every frame.

RenderCache::clear() releases the backing Vec allocation (not just clearing entries), preventing memory accumulation across long sessions. RenderCache::shift(count) efficiently removes the oldest entries when messages are trimmed during compaction, avoiding a full re-render.

Architecture

The TUI runs as three concurrent loops:

1. Crossterm event reader — dedicated OS thread (std::thread), sends key/tick/resize events via mpsc
2. TUI render loop — tokio task, draws frames at 10 FPS via tokio::select!, polls watch::Receiver for latest metrics before each draw
3. Agent loop — existing Agent::run(), communicates via TuiChannel and emits metrics via watch::Sender

TuiChannel implements the Channel trait, so it plugs into the agent with zero changes to the generic signature. MetricsSnapshot and MetricsCollector live in zeph-core to avoid circular dependencies — zeph-tui re-exports them.

Configuration

[tui]
show_source_labels = true   # Show [user]/[zeph]/[tool] prefixes on messages (default: true)

Set show_source_labels = false to hide the source label prefixes from chat messages for a cleaner look. Environment variable: ZEPH_TUI_SHOW_SOURCE_LABELS.

Tracing

When TUI is active, tracing output is redirected to zeph.log to avoid corrupting the terminal display.

Docker

Docker images are built without the tui feature by default (headless operation). To build a Docker image with TUI support:

docker build -f docker/Dockerfile.dev --build-arg CARGO_FEATURES=tui -t zeph:tui .

Testing

The TUI has a dedicated test automation infrastructure covering widget snapshots, integration tests with mock event sources, property-based layout fuzzing, and E2E terminal tests. See TUI Testing for details.