# 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