zeph-tui

Ratatui-based TUI dashboard with real-time metrics 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. 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_palette — fuzzy-matching command palette with daemon commands (daemon:connect, daemon:disconnect, daemon:status), action commands (app:quit, app:help, session:new, app:theme), and keybinding hints
• event — AgentEvent, AppEvent, EventReader for async event dispatch
• file_picker — @-triggered fuzzy file search with nucleo-matcher and ignore crate
• highlight — syntax highlighting for code blocks
• hyperlink — OSC 8 clickable hyperlinks for bare URLs and markdown links
• layout — panel arrangement and responsive grid
• 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 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)
• error — TuiError typed error enum (Io, Channel)

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.

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.

Command palette

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

Features

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

MIT