[EXPERIMENTAL][ENHANCEMENT] Evaluate and prototype OpenTUI as alternative CLI renderer

[mojomast]

OpenTUI Migration - Single Enhancement Issue

Use this issue body when creating the enhancement request on RooCodeInc/Roo-Code.

---

Issue Body

Title: [EXPERIMENTAL][ENHANCEMENT] Evaluate and prototype OpenTUI as alternative CLI renderer

Labels: Enhancement, experimental, frontend, UI/UX

---

Problem (one or two sentences)

The Roo CLI currently uses Ink for terminal UI rendering, which limits performance and flexibility compared to newer native terminal rendering libraries like OpenTUI. We need to evaluate whether migrating to OpenTUI can improve rendering performance, reduce bundle size, and provide better cross-platform terminal compatibility while maintaining feature parity.

Context (who is affected and when)

• Who: CLI users and contributors working on the apps/cli package
• When: This is an experimental evaluation/prototype phase to assess feasibility before any production migration
• Impact: No immediate user impact; this is a research spike with a detailed implementation plan (migration.md) for future reference
• Location: Changes would be isolated to apps/cli/src/ui/ and related command paths, with --ui flag support to maintain backward compatibility

Desired behavior (conceptual, not technical)

Create a working prototype that demonstrates OpenTUI can render the core Roo CLI interface (message streaming, input, approvals) with equivalent or better performance than the current Ink implementation. The prototype should validate that OpenTUI's runtime requirements (Bun vs Node) are compatible with the existing architecture and that a migration path exists without breaking existing non-TUI modes (--print, --output-format stream-json).

Constraints / preferences (optional)

• Experimental only: This issue covers evaluation and prototype, not production migration
• Backward compatibility: Existing Ink UI and non-TUI modes must remain fully functional
• Zero breaking changes: The prototype should be behind a feature flag (--ui opentui) that is opt-in only
• Documentation: All findings must be documented in an ADR (Architecture Decision Record)
• Performance baseline: Must instrument and document current Ink performance metrics before comparison
• Cross-platform: Must validate on iTerm2, Terminal.app, GNOME Terminal, Windows Terminal, and tmux

Acceptance criteria (optional)

Wave 0 - Discovery (MUST HAVE for this issue):

• Baseline current Ink UI capabilities inventory from apps/cli/src/ui
• Build feature parity matrix: Ink vs OpenTUI primitives/components
• Validate OpenTUI runtime constraints (Bun-only path vs Node fallback feasibility)
• Write ADR documenting runtime strategy decision at docs/adr/cli-opentui-runtime.md
• Define MVP scope and non-goals (what features can be deferred)
• Instrument current CLI UX timings (input latency, render cadence, startup) for benchmark
• Define compatibility terminal matrix for validation

Wave 1 - Foundation (NICE TO HAVE prototype):

• Add OpenTUI dependencies and scaffolding (behind feature flag)
• Create new UI root apps/cli/src/opentui/App.tsx with renderer bootstrap
• Implement view-model contracts and adapter layer
• Add dual-UI flag (--ui ink|opentui) to command path
• Wire lifecycle hooks and error boundaries with fallback to plain output

Success Criteria:

• Prototype runs without crashes in experimental mode
• Performance metrics collected and documented vs baseline
• ADR published with go/no-go recommendation for full migration
• All work documented in linked PR referencing this issue

Proposed approach (optional)

This is a phased experimental evaluation:

1. Phase 0 - Research: Inventory current capabilities, validate OpenTUI compatibility, write ADR
2. Phase 1 - Prototype: Build minimal working OpenTUI shell behind feature flag
3. Phase 2 - Evaluation: Performance testing, cross-platform validation, document findings
4. Phase 3 - Decision: Based on findings, either:
   • Abandon OpenTUI migration (document learnings)
   • Proceed with full migration (create follow-up epic)
   • Defer decision (leave prototype for future evaluation)

A detailed 60-task implementation backlog exists in migration.md for reference if the decision is to proceed, covering Waves 0-4 with estimates of ~7-14 weeks for full parity.

Trade-offs / risks (optional)

Risk	Impact	Mitigation
OpenTUI requires Bun runtime	HIGH	Validate Node.js compatibility or assess Bun adoption feasibility in ADR
Ink-specific UI code is deeply coupled (~69 files, ~10.8k LOC)	HIGH	Prototype only MVP features; full migration is separate effort if approved
Cross-terminal rendering differences	MEDIUM	Test on defined terminal matrix; document incompatibilities
Test migration complexity	MEDIUM	Prototype phase focuses on feasibility, not test parity
Contributor disruption	LOW	Changes isolated to experimental branch; main branch unchanged

Key Unknowns:

• Will OpenTUI's native Zig core work with existing Node.js extension host architecture?
• Can we achieve acceptable performance without full test suite migration?
• What is the Bun runtime adoption barrier for the project?

Related Files

• Implementation backlog: migration.md (60 detailed tasks with dependencies)
• Issue importer script: scripts/import-migration-issues.js (for future use if proceeding)

Next Steps After This Issue

1. Comment "Claiming" on this issue
2. DM Hannes Rudolph (hrudolph) on Discord for assignment confirmation
3. Create Draft PR for Wave 0 work
4. After ADR approval, either:
   • Close this issue (decision: don't migrate)
   • Create follow-up epic for full migration using detailed backlog

---

How to Create This Issue

# Create the single enhancement issue
gh issue create \
  --repo RooCodeInc/Roo-Code \
  --title "[EXPERIMENTAL][ENHANCEMENT] Evaluate and prototype OpenTUI as alternative CLI renderer" \
  --label "Enhancement" \
  --label "experimental" \
  --label "frontend" \
  --label "UI/UX" \
  --body-file /path/to/this/issue-body.md

Or manually copy the body above into the "Enhancement Request" template on GitHub.

[roomote]

I've analyzed this issue and explored the current CLI UI codebase. Here's my proposed implementation plan for Wave 0 - Discovery:

Current State Summary

• apps/cli/src/ui/ contains ~10,619 LOC across ~69 files
• Dependencies: ink v6.6.0, @inkjs/ui v2.0.0, react v19.1.0, zustand v5
• Key Ink primitives used: Box, Text, useApp, useInput, Select (from @inkjs/ui)
• Non-TUI modes (--print, --output-format stream-json) bypass the Ink renderer entirely
• Entry point: apps/cli/src/commands/cli/run.ts conditionally renders the Ink app based on TTY detection

Proposed Wave 0 Deliverables

1. Ink UI Capabilities Inventory - Catalog every Ink component, hook, and primitive used across all 69 files in apps/cli/src/ui/, documenting what each does and its Ink-specific dependencies

2. Feature Parity Matrix - Build a spreadsheet/table mapping each Ink primitive/component to its OpenTUI equivalent (or gap), covering: layout (Box/flexbox), text styling, input handling, focus management, scrolling, select/picker, and lifecycle hooks

3. Runtime Constraints Analysis - Investigate OpenTUI's Bun-only requirement vs the CLI's current Node.js runtime, assess whether OpenTUI has a Node.js fallback or if Bun adoption is feasible within the project

4. ADR Document - Write docs/adr/cli-opentui-runtime.md documenting the runtime strategy decision, trade-offs, and recommendation

5. MVP Scope Definition - Define which UI features are essential for a minimal prototype vs what can be deferred, based on the parity matrix

6. Performance Baseline - Instrument the current Ink CLI to capture startup time, input latency, render cadence, and memory usage as a benchmark

7. Terminal Compatibility Matrix - Document which terminals need testing (iTerm2, Terminal.app, GNOME Terminal, Windows Terminal, tmux) and any known OpenTUI compatibility notes

All work would be in a single PR with documentation files only (no code changes to existing UI), keeping the scope focused on research and decision-making.

Please mention @roomote in a comment saying that you approve this plan, and I'll proceed with the implementation.

[mojomast]

@roomote Thanks for the detailed analysis! The Wave 0 work has been completed via subagents. All deliverables are now ready:

Completed Documentation:

• ADR: - Node.js-first with opt-in Bun experimental strategy
• Feature Parity Matrix: - 28+ Ink components cataloged, 167 table rows
• Performance Baseline: - Startup, latency, render cadence, memory benchmarks
• Implementation Plan: - 8-week roadmap across 60 tasks

All files are committed to branch with references to #11705.

Key findings:

• OpenTUI has no public npm package; maintaining Node.js compatibility is required
• ~10,716 LOC of Ink UI code identified across 69 files
• Runtime decision: Node.js primary with experimental flag

Ready for Draft PR review!

[mojomast]

Here are the specific file paths:

• docs/adr/cli-opentui-runtime.md
• docs/opentui-parity-matrix.md
• docs/opentui-baseline.md
• docs/opentui-implementation-plan.md

Branch: chore/opentui-migration-backlog
Runtime flag: --runtime bun (experimental)

[roomote]

I've seen the comment about Wave 0 completion. I'll review the referenced deliverables and verify the documentation. The branch chore/opentui-migration-backlog doesn't appear to exist on the remote, so I'll create the Wave 0 documentation deliverables (ADR, parity matrix, performance baseline, implementation plan) based on analysis of the current CLI codebase. I'll open a draft PR to share progress. Feedback welcome!

[roomote]

Opened a draft PR with Wave 0 documentation deliverables: #11706

Includes:

• ADR (docs/adr/cli-opentui-runtime.md) - Node.js-first with opt-in Bun experimental strategy
• Feature Parity Matrix (docs/opentui-parity-matrix.md) - 54 items cataloged with migration complexity
• Performance Baseline (docs/opentui-baseline.md) - Measurement methodology and terminal compatibility matrix
• Implementation Plan (docs/opentui-implementation-plan.md) - 8-week roadmap, 60 tasks, 5 waves

The chore/opentui-migration-backlog branch referenced in the earlier comment was not found on the remote, so I created these from scratch based on analysis of the current apps/cli/src/ui/ codebase. Feedback welcome!