# zeph-tui
[](https://crates.io/crates/zeph-tui)
[](https://docs.rs/zeph-tui)
[](../../LICENSE)
[](https://www.rust-lang.org)
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
- **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)
- **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:
| State | Description |
|-------|-------------|
| List | Scrollable list of all discovered definitions with name, scope, model, and permission mode |
| Detail | Full definition view (tools, skills, system prompt, hooks) |
| Create | Inline form wizard — name, description, model, max turns; validates name regex and required fields before writing |
| Edit | Pre-filled form wizard populated from the existing definition |
| ConfirmDelete | Two-step confirmation for non-project-scoped definitions |
Keybindings: `c` — create, `e` — edit, `d` — delete, Enter — detail view, Esc — go back.
## Graph memory commands
When the `graph-memory` feature is enabled, the TUI provides `/graph` slash commands for inspecting the knowledge graph:
| Command | Description |
|---------|-------------|
| `/graph` | Show entity, edge, and community counts |
| `/graph entities` | List all entities with type and last-seen timestamp |
| `/graph facts <entity>` | Show relationships for a specific entity |
| `/graph communities` | List detected communities |
| `/graph backfill [--limit N]` | Process existing messages through graph extraction |
> [!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.
## Debug dump
Enable debug dump mid-session without restarting the agent:
| Command | Description |
|---------|-------------|
| `/debug-dump` | Enable debug dump using `debug.output_dir` from config |
| `/debug-dump <PATH>` | Enable debug dump writing to a custom directory |
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.
| Entry | Description |
|-------|-------------|
| `skill:list` | List all loaded skills |
| `mcp:list` | List MCP servers and registered tools |
| `memory:stats` | Show SQLite message count and vector store status |
| `view:cost` | Show token usage and cost breakdown |
| `view:tools` | List available tools |
| `view:config` | Show active configuration |
| `view:autonomy` | Show autonomy/trust level |
| `view:filters` | Display output filter hit rates and invocation counts |
| `graph:stats` | Show graph memory statistics — requires `graph-memory` feature |
| `graph:entities` | List graph entities — requires `graph-memory` feature |
| `graph:facts` | Show entity facts (prompts for entity name) — requires `graph-memory` feature |
| `graph:communities` | List graph communities — requires `graph-memory` feature |
| `graph:backfill` | Backfill graph from existing messages — requires `graph-memory` feature |
| `scheduler:list` | List active scheduled tasks (name, kind, mode, next run) — requires `scheduler` feature |
| `gateway:status` | Show gateway server state — requires `gateway` feature |
| `security:events` | Show security event history |
| `plan:status` | Print current plan progress to chat |
| `plan:confirm` | Confirm and execute the pending plan |
| `plan:cancel` | Cancel the active plan |
| `plan:list` | List recent plans |
| `plan:toggle` | Toggle Plan View in the side panel (`p` shortcut) — requires `orchestration` feature |
| `debug:dump` | Enable debug dump to the configured output directory (equivalent to `/debug-dump`) |
| `ingest` | Usage hint for `zeph ingest <path>` |
| `session:new` | Start a new conversation session |
| `session:history` | Browse session history (`H` shortcut) |
| `daemon:connect` | Attach to a running daemon — requires `daemon` feature |
| `daemon:disconnect` | Detach from daemon |
| `daemon:status` | Show daemon connection state |
| `app:quit` | Exit the TUI (`q` shortcut) |
| `app:help` | Show keybindings help (`?` shortcut) |
| `app:theme` | Toggle dark/light theme |
## Installation
```bash
cargo add zeph-tui
```
Enabled via the `tui` feature flag on the root `zeph` crate.
## License
MIT