zeph-tui

Ratatui-based TUI dashboard with real-time metrics and multi-session support for Zeph.

Overview

Provides a terminal UI for monitoring the Zeph agent in real time. Built on ratatui and crossterm, it renders live token usage, latency histograms, conversation history, and skill activity. The skills panel includes Wilson score confidence bars showing each skill's posterior reliability estimate. Supports multiple concurrent sessions via SessionRegistry — cycle between sessions with /session next / /session prev (or the session:next / session:prev palette entries) and close them with /session close. Feature-gated behind tui.

Key Modules

• app — App state machine driving the render/event loop; uses a dirty flag to skip redraws when state is unchanged, reducing idle CPU usage
• channel — TuiChannel implementing the Channel trait for agent I/O
• command — TuiCommand plus the fuzzy-matched palette registries: command_registry() (view / session / app / plugin entries), daemon_command_registry() (daemon:connect, daemon:disconnect, daemon:status), and extra_command_registry() (infra, agent/plan, graph/experiment, cocoon, clipboard, knowledge entries)
• event — AgentEvent, AppEvent, EventReader for async event dispatch
• file_picker — FileIndex, the background-built, recency-ordered workspace file index (ignore crate) that feeds the @ mention picker; it is a data source only, no longer a UI surface of its own
• highlight — syntax highlighting for code blocks
• hyperlink — OSC 8 clickable hyperlinks for bare URLs and markdown links
• layout — panel arrangement and responsive grid; fit_panel_heights is the integer max-min fair water-filling allocator that sizes the four side-panel slots from their PanelDemands (Collapsed / Rows(n) / Greedy), and AppLayout::compute takes a PanelSizing (per-slot demands + focused slot) rather than a plain visibility flag set
• metrics — MetricsCollector, MetricsSnapshot for live telemetry; skill confidence bars rendered as [████░░░░] 73% (42 uses) using Wilson score posterior from the skills registry; filter savings percentage shown in the status bar (e.g. Filters: 78%); SEC indicator in status bar shows injection flag count when nonzero; compaction probe metrics panel showing pass/soft-fail/fail/error rates; Backfilling embeddings: N/M (X%) status bar entry during embed backfill (clears on completion)
• theme — color palette and style definitions
• widgets — reusable ratatui widget components; includes mention_picker (the inline @ popup, see below); subagents widget with a 5-state FSM panel (List → Detail → Create → Edit → ConfirmDelete) for interactive management of sub-agent definition files; security widget renders a side panel with a real-time security event feed (injection flags, exfiltration blocks, quarantine invocations, truncations); plan_view widget renders a live task graph table with per-row status spinners, status colors (Running=Yellow, Completed=Green, Failed=Red), and a 30-second stale cleanup — toggled with p (requires orchestration feature); memory widget displays compaction probe metrics (pass/soft-fail/fail/error distribution with percentage bars); settings widget renders a read-only, tabbed (Providers / MCP / Agents) view of live configuration sourced from MetricsSnapshot, toggled with S; transcript_search widget implements a Ctrl+F highlight-and-scroll transcript search overlay (mirrors the Ctrl+R reverse-search pattern); task_registry widget shows the live TaskSupervisor task list, toggled with t
• error — TuiError typed error enum (Io, Channel)

Interrupt and quit (Ctrl+C)

Ctrl+C is handled globally, ahead of every overlay and input mode, and its meaning depends on whether the agent is working:

While a turn is running, the input separator row carries a ctrl+c to interrupt hint. q (normal mode) and the app:quit palette entry remain the direct exit paths; Esc no longer quits, and is reserved for dismissing overlays and leaving insert mode.

Inline @ mention picker

Typing @ in the input opens a non-modal popup above the input row. It never steals keystrokes: every character still lands in the input buffer, and the picker derives its query from the buffer, so cursor movement, paste, and backspace all behave normally. On an empty query, results are ordered by recency (uncommitted changes first, then mtime descending) from the background-built FileIndex.

Results are grouped into category tabs — All, Files, Skills, Agents — capped at 10 entries.

Moving the cursor out of the @query span closes the popup automatically.

Side-panel sizing

Side panels are sized from their own content by default. fit_panel_heights grants each visible slot at least one identity row, never more rows than it asked for, and leaves any surplus as blank space at the bottom of the column.

[tui]
panel_sizing = "auto"   # or "even"

Switch at runtime with /panel_sizing (toggles), /panel_sizing auto, /panel_sizing even, or the app:panel-sizing palette entry. Individual panels can still be pinned to a single summary row independently of this setting.

Agents management panel

Press a in the TUI to open the interactive agents panel. It provides full CRUD over sub-agent definition files without leaving the terminal UI:

Keybindings: c — create, e — edit, d — delete, Enter — detail view, Esc — go back.

SubAgents sidebar and transcript viewer

The SubAgents side panel (a keybinding) was extended in v0.18.1 with live status tracking for running sub-agents and an inline transcript viewer.

When a sub-agent is active, the panel shows a spinner alongside the agent name and its current tool/status line. Completed agents display their final turn count.

Transcript viewer — press j/k to navigate the agent list, then Enter to open the full JSONL transcript for the selected agent in a scrollable overlay. The overlay renders each turn with role label, timestamp, and message content. Press Esc to dismiss.

[!NOTE] The transcript viewer reads from the persistent JSONL transcript stored by zeph-core. Transcripts are available for both active and completed agents as long as the session file exists. Use /agent resume <id> to continue a completed session.

Live transcript forwarding — when agents.forward_transcript = true (env ZEPH_AGENTS_FORWARD_TRANSCRIPT, CLI --forward-subagent-text), the runtime subagent detail view splits to show a bounded, auto-scrolling tail of the selected sub-agent's full, untruncated per-turn text/thinking output as it is produced — instead of only the existing 120-char once-per-turn status snippet. The panel falls back to the unchanged list-only layout when nothing has been forwarded yet or the area is too short to usefully split.

[!NOTE] Forwarding is opt-in and defaults to false (zero behavior change when disabled). Forwarded content passes through ContentSanitizer plus the optional SecretMaskRegistry/PiiFilter layers before reaching the panel.

Durable panel

Press D (or the durable command-palette entry) to open a live view of zeph-durable executions — status, name, and progress per row, polled every 5 seconds. The header shows the active AEAD/HMAC key_id and, when a key-rotation window is open ([durable] previous_key_id set), a passive rotation window open (previous_key_id = N) indicator plus a matching low-priority status-bar chip. This is read-only visibility — the panel offers no rotation action; rotation stays a restart-required CLI-only operation (zeph durable rotate-key).

Graph memory commands

When the graph-memory feature is enabled, the TUI provides /graph slash commands for inspecting the knowledge graph:

[!NOTE] These commands require --features graph-memory (or --features full). The graph must be enabled in config ([memory.graph] enabled = true) or via the --graph-memory CLI flag.

Experiment commands

When the experiments feature is enabled, the TUI provides /experiment slash commands for autonomous self-experimentation:

[!NOTE] These commands require --features experiments (or --features full). Experiments must be enabled in config ([experiments] enabled = true).

Debug dump

Enable debug dump mid-session without restarting the agent:

Files are written to {output_dir}/{unix_timestamp}/ with numbered request.json, response.txt, and tool-{name}.txt files for each LLM call and tool execution.

Settings view

Press S (or the settings command-palette entry) to open a read-only, tabbed view of the running session's live configuration, sourced from MetricsSnapshot:

Write/edit is out of scope for this view — it is read-only by design.

Transcript search

Press Ctrl+F (or the search:transcript command-palette entry) to open a case-insensitive substring search overlay over the conversation transcript, mirroring the existing Ctrl+R reverse-search interaction: highlight-and-scroll (not filter), cycle matches, Esc restores the pre-search scroll position, Enter accepts.

Command palette

The command palette is opened with : in normal mode. Type to fuzzy-filter entries, then press Enter to execute.

Entries come from three registries in the command module — command_registry() (core), daemon_command_registry(), and extra_command_registry() — which are the authoritative source for the current set.

Core — views and panels

Core — sessions and app

Daemon

Extra — diagnostics, memory, agents, plans

Features

Feature-gated command-palette and slash entries (e.g. graph:*, experiment:*, plan:*, scheduler:*, gateway:*, daemon:*) are driven by feature flags on the root zeph crate, not by this crate directly.

Installation

cargo add zeph-tui

Enabled via the tui feature flag on the root zeph crate:

cargo run --features tui -- --tui

Documentation

Full documentation: https://bug-ops.github.io/zeph/

License

Licensed under either of MIT or Apache License, Version 2.0 at your option.