stack/docs/TASKS-TUI_Improvements.md

Tasks: TUI Improvements

Branch: feat/p7-tui-improvements Worktree: /home/jwoltje/src/mosaic-mono-v1-worktrees/tui-improvements PRD: PRD-TUI_Improvements.md

---

Wave 1 — Status Bar & Polish ✅

ID	Task	Status	Notes
TUI-001	Component architecture — split app.tsx into TopBar, BottomBar, MessageList, InputBar, hooks	✅ done	79ff308
TUI-002	Top status bar — branded mosaic icon, version, model, connection indicator	✅ done	6c2b01e
TUI-003	Bottom status bar — cwd, git branch, token usage, session ID, gateway status	✅ done	e8d7ab8
TUI-004	Message formatting — timestamps, role colors (❯ you / ◆ assistant), word wrap	✅ done	79ff308
TUI-005	Quiet disconnect — single indicator, auto-reconnect, no error flood	✅ done	79ff308
TUI-006	Tool call display — inline spinner + tool name during execution, ✓/✗ on completion	✅ done	79ff308
TUI-007	Thinking/reasoning display — dimmed 💭 block for agent:thinking events	✅ done	79ff308
TUI-007b	Wire token usage, model info, thinking levels end-to-end (gateway → types → TUI)	✅ done	a061a64
TUI-007c	Ctrl+T to cycle thinking levels via set:thinking socket event	✅ done	a061a64

Wave 2 — Layout & Navigation (next)

ID	Task	Status	Notes
TUI-008	Conversation sidebar — list, create, switch conversations	not-started	Depends: TUI-001
TUI-009	Keybinding system — Ctrl+N, Ctrl+L, Ctrl+K	not-started	Depends: TUI-008
TUI-010	Scrollable message history — viewport with PgUp/PgDn	not-started	Depends: TUI-001
TUI-011	Message search — find in current conversation	not-started	Depends: TUI-010

Wave 3 — Advanced Features

ID	Task	Status	Notes
TUI-012	Project/mission views	not-started
TUI-013	Agent status monitoring	not-started
TUI-014	Settings/config screen	not-started
TUI-015	Multiple agent sessions	not-started

---

Handoff Notes

File Structure

packages/cli/src/tui/
├── app.tsx                          ← Thin shell composing all components
├── components/
│   ├── top-bar.tsx                  ← Mosaic icon + version + model + connection
│   ├── bottom-bar.tsx               ← 3-line footer: gateway, cwd+session, tokens+model
│   ├── message-list.tsx             ← Messages, tool calls, thinking, streaming
│   └── input-bar.tsx                ← Bordered prompt with context-aware placeholder
└── hooks/
    ├── use-socket.ts                ← Typed Socket.IO (all ServerToClient/ClientToServer events)
    └── use-git-info.ts              ← Reads cwd + git branch at startup

Cross-Package Changes

• packages/types/src/chat/events.ts — Added SessionUsagePayload, SessionInfoPayload, SetThinkingPayload, session:info event, set:thinking event
• apps/gateway/src/chat/chat.gateway.ts — Emits session:info on session creation, includes usage in agent:end, handles set:thinking

Key Design Decisions

• Footer is 3 lines: (1) gateway status right-aligned, (2) cwd+branch left / session right, (3) tokens left / provider+model+thinking right
• Mosaic icon uses brand colors in windmill cross pattern with GAP const to prevent prettier collapsing spaces
• flexGrow={1} on header text column prevents re-render artifacts
• Token/model data comes from gateway via agent:end payload and session:info events
• Thinking level cycling via Ctrl+T sends set:thinking to gateway, which validates and responds with session:info

How to Run

cd /home/jwoltje/src/mosaic-mono-v1-worktrees/tui-improvements
pnpm --filter @mosaic/cli exec tsx src/cli.ts tui
# or after build:
node packages/cli/dist/cli.js tui --gateway http://localhost:4000

Quality Gates

pnpm --filter @mosaic/cli typecheck && pnpm --filter @mosaic/cli lint
pnpm --filter @mosaic/gateway typecheck && pnpm --filter @mosaic/gateway lint
pnpm --filter @mosaic/types typecheck