Keprix TUI¶

The Textual-based terminal UI is the Keprix Command Center. It connects to the workspace API on port 3333, can use HTTP, WebSocket, or in-process runtime transports, and keeps the Keprix look while preserving the agent behaviors adopted from Hermes.

Basics¶

• Start the backend with keprix start, then launch the TUI from the installed CLI.
• Sessions, models, streaming replies, clarify and approval overlays, virtual scrollback, command palette, status bar, and runtime panels are built in.
• Slash commands use local handlers first, then backend fallthrough. See TUI slash reference.
• The left pane is the operator cockpit: sessions, runtime health, queue state, gateway state, tools, skills, plugins, and command hints.
• The main pane is the transcript, tool trail, details view, and review surface.
• The bottom pane is the composer with slash completion, busy-mode behavior, paste handling, and voice compose.

Command Center surfaces¶

First run and setup¶

Three surfaces share setup state via GET /api/setup/status:

Launch the Textual TUI with keprix tui after keprix start.

When no provider is configured:

• The TUI shows a Setup required overlay (provider, API key, optional model).
• Enter saves via POST /api/setup/minimal.
• f runs full setup (keprix setup) as a subprocess handoff.
• d prints the first-run docs URL.
• /setup [section] and /model (when unconfigured) also hand off to the CLI wizard.

keprix --tui with no provider skips the CLI exit prompt and opens the Textual TUI in setup mode (KEPRIX_SETUP_REQUIRED=1).

Advanced¶

Busy input modes¶

While the agent is working, input can interrupt (/busy interrupt), queue messages (/busy queue), or steer the current turn (/busy steer). Override persists locally until changed again.

Details sections¶

Use /details to list section visibility modes:

Examples:

• /details tools expanded shows the full tool trail during a turn.
• /details all collapsed resets every section.

Configure defaults in workspace config:

display:
  details:
    thinking: collapsed
    tools: collapsed
    subagents: collapsed
    activity: hidden
  compose_key: ctrl+g
  voice:
    enabled: true
    record_key: ctrl+b

External editor compose¶

Press Ctrl+G (or the configured display.compose_key) to suspend the TUI and open $EDITOR on the current composer text. On save, trimmed text returns to the input. Set EDITOR or VISUAL if you see Set EDITOR to use external compose.

Voice push-to-talk¶

Press Ctrl+B to toggle recording when voice is enabled (/voice on). Audio is sent to POST /api/audio/transcribe; the transcript is inserted into the composer without auto-send.

Optional capture backends (git or checkout; PyPI bare install not published yet):

pipx install 'keprix[tui-voice] @ git+https://github.com/malike2356/keprix.git'
# or from a local checkout:
pipx install '.[tui-voice]' --force

Without the extra, the TUI falls back to arecord or ffmpeg when present.

Large paste collapse¶

Pastes over 2000 characters collapse to [Pasted N lines, expanded on send] so the composer stays responsive. The full text is restored on submit.

Slash fallthrough¶

Unknown local slash commands fall through to the backend /api/slash/exec and /api/command/dispatch pipeline. User-visible failures are sanitized; raw HTTPStatusError, workspace identifiers, channel identifiers, and backend tracebacks must not be printed into the transcript.

Hermes parity matrix¶

The current parity target is full behavioral parity without copying Hermes look and feel. Keprix keeps its own layout, visual language, and product extensions.

Validation¶

Use the TUI checks after changing runtime, renderer, command, or theme code:

# Prefer project venv Python 3.11+
.venv/bin/python -m pytest tests/tui -q
bash scripts/check-tui-parity.sh
bash scripts/check-tui-surpass-hermes.sh
bash scripts/check-agent-parity.sh
bash scripts/check-private-ship-gate.sh

check-tui-parity.sh proves the 100/100 Hermes behavior contract. check-tui-surpass-hermes.sh proves Keprix Command Center and superiority contracts on top of parity. check-agent-parity.sh covers agent runtime alignment. check-private-ship-gate.sh bundles those gates with architecture, auth, billing, and frontend typecheck for private soft ship.

As of 2026-07-27, the TUI suite covers slash commands, command palette, renderer contracts, runtime transports, keyboard behavior, terminal capability detection, theme contrast, fault recovery, review mode, tool cards, session map, and the Command Center proof contracts.

Optional dependencies¶

Install from GitHub or a local checkout (PyPI package keprix is not published yet):

pipx install 'keprix[tui] @ git+https://github.com/malike2356/keprix.git'          # Textual UI
pipx install 'keprix[tui-voice] @ git+https://github.com/malike2356/keprix.git'    # sounddevice + numpy capture
# or from a checkout:
# pipx install '.[tui]' --force
# pipx install '.[tui-voice]' --force

See install.md and pypi-publish-checklist.md.