Epic: Ink-based TUI Rewrite for oclite #11762

Overview

Replace the current log-update based lite UI with Ink (React for terminals) to solve fundamental rendering issues with concurrent state updates.

Background

The current oclite lite implementation (17 files, ~2,500 lines) has persistent issues:

• pausedForProse hack prevents live block updates during text streaming to avoid crashes
• Child session mapping requires complex buffering for out-of-order events
• State synchronization between SDK events and UI is fragile
• log-update wasn't designed for this level of complexity

Why Ink?

1. <Static> component — Renders completed items permanently above dynamic content (exactly what we need)
2. React reconciler — Multiple state updates batch properly, no need for pausedForProse hacks
3. useStdout().write() — Can output text without interfering with render cycle
4. Battle-tested — Claude Code, Gemini CLI, Cloudflare Wrangler all use Ink

Package Versions

Scope

In Scope

• Replace all rendering logic with Ink components
• Maintain feature parity with current lite functionality
• SDK event stream integration via React hooks
• Child session status display (the feature that keeps breaking)

Out of Scope

• Full opencode TUI feature parity (panels, scrolling, etc.)
• Web UI
• Desktop app

Child Issues (Implementation Order)

Phase 1: Setup

• Setup Ink dependencies and verify Bun compatibility #11763 - Setup Ink dependencies and verify Bun compatibility (0.5 days)

Phase 2: Core Architecture

• Implement core App component and state management #11764 - Implement core App component and state management (1.5 days)
• Implement theming system for Ink components #11776 - Implement theming system (0.5 days)

Phase 3: Components

• Implement StreamingProse component with markdown rendering #11765 - Implement StreamingProse component with markdown (2 days)
• Implement ToolDisplay component #11766 - Implement ToolDisplay component (1 day)
• Implement TaskDisplay component with child tool status #11767 - Implement TaskDisplay with child tool status (1.5 days)
• Implement Static component integration for completed messages #11768 - Implement Static component integration (1 day)
• Implement TextInput component with useInput hook #11769 - Implement TextInput component (1.5 days)
• Implement SelectMenu component #11770 - Implement SelectMenu component (0.5 days)
• Implement StatusBar component #11774 - Implement StatusBar component (0.5 days)

Phase 4: Integration

• Implement useSDKEvents hook for event stream integration #11771 - Implement useSDKEvents hook (2.5 days) ⚠️ HIGH RISK
• Implement useStreaming hook for chat responses #11772 - Implement useStreaming hook (1.5 days)
• Implement slash command system #11773 - Implement slash command system (1 day)

Phase 5: Polish & Ship

• Integration testing and edge case handling #11777 - Integration testing and edge cases (3.5 days)
• Build configuration and binary optimization #11778 - Build configuration and optimization (1 day)
• Documentation: Upstream sync workflow #11779 - Documentation: Upstream sync workflow (0.5 days)

Success Criteria

• No crashes during prose streaming + tool updates
• Child task status updates display correctly
• Binary size < 15MB
• All current working features preserved
• Tests for critical rendering paths

Estimated Total Effort

~20 days (4 weeks of focused work)

Risk Assessment

Branch

feature/oclite-ink-rewrite (clean branch from dev)

Backup

Previous experimental work saved in: backup/oclite-lite-experiments-2026-02-02