stack/docs/PRD-TUI_Improvements.md

PRD: TUI Improvements — Phase 7

Branch: feat/p7-tui-improvements Package: packages/cli Status: In Progress

---

Problem Statement

The current Mosaic CLI TUI (packages/cli/src/tui/app.tsx) is a minimal single-file Ink application with:

• Flat message list with no visual hierarchy
• No system context visibility (cwd, branch, model, tokens)
• Noisy error messages when gateway is disconnected
• No conversation management (list, switch, rename, delete)
• No multi-panel layout or navigation
• No tool call visibility during agent execution
• No thinking/reasoning display

The TUI should be the power-user interface to Mosaic — informative, responsive, and visually clean.

---

Goals

Wave 1 — Status Bar & Polish (MVP)

Provide essential context at a glance and reduce noise.

1. Top status bar — shows: connection indicator (●/○), gateway URL, agent model name
2. Bottom status bar — shows: cwd, git branch, token usage (input/output/total)
3. Better message formatting — distinct visual treatment for user vs assistant messages, timestamps, word wrap
4. Quiet disconnect — single-line indicator when gateway is offline instead of flooding error messages; auto-reconnect silently
5. Tool call display — inline indicators when agent uses tools (spinner + tool name during execution, ✓/✗ on completion)
6. Thinking/reasoning display — collapsible dimmed block for agent:thinking events

Wave 2 — Layout & Navigation

Multi-panel layout with keyboard navigation.

1. Conversation sidebar — list conversations, create new, switch between them
2. Keybinding system — Ctrl+N (new conversation), Ctrl+L (conversation list toggle), Ctrl+K (command palette concept)
3. Scrollable message history — viewport with PgUp/PgDn/arrow key scrolling
4. Message search — find in current conversation

Wave 3 — Advanced Features

1. Project/mission views — show active projects, missions, tasks
2. Agent status monitoring — real-time agent state, queue depth
3. Settings/config screen — view/edit connection settings, model preferences
4. Multiple agent sessions — split view or tab-based multi-agent

---

Technical Approach

• Ink 5 (React for CLI) — already in deps
• Component architecture — break monolithic app.tsx into composable components
• Typed Socket.IO events — leverage @mosaic/types ServerToClientEvents / ClientToServerEvents
• Local state only (Wave 1) — cwd/branch read from process.cwd() and git at startup
• Gateway metadata (future) — extend socket handshake or add REST endpoint for model info, token usage

---

Non-Goals (for now)

• Image rendering in terminal
• File editor integration
• SSH/remote gateway auto-discovery