# TUI

The Voxcode TUI is the interactive terminal interface for real-time agent workflows. It renders in an immediate-mode style with keyboard-first controls.

## Capabilities

- Live streaming responses from the agent
- Tool execution feedback with status indicators
- Session history navigation and branching
- Keyboard-first controls with editor, suggestions, and selection UI

## Interface Layout

The TUI is organized into several panels:

- **Editor panel** — multi-line input with syntax highlighting and placeholder text
- **Output area** — streaming agent responses with ANSI-colored output
- **Footer bar** — status indicators (model, mode, session info) with optional extension statuses
- **Overlays** — non-blocking popups for confirmations and notifications
- **Selectors** — model picker, skills browser, session history (replaces editor temporarily)

## Rendering

The TUI uses an immediate-mode renderer with the following characteristics:

- **Throttle**: 75ms per-keystroke throttle; force-render bypasses via `requestRender({ force: true })`
- **Viewport**: auto-resets scroll offset when content shrinks beyond 50%
- **Resize**: coordinates clamp to 0 if the terminal shrinks past content
- **Truncation**: ANSI-aware truncation for proper width calculation with styled text

## Configuration

TUI behavior is configured via settings:

```json
{
  "tui": {
    "showLineNumbers": true,
    "minEditorHeight": 3,
    "scrollback": 5000
  }
}
```

For setup and terminal compatibility, see [terminal-setup.md](terminal-setup.md).
