Architectural Reasoning

The Premise

You want to build a secure AI agent orchestration tool with a terminal-native workflow. The key insight is that you prefer the TUI experience of tools like opencode, but want web accessibility without the complexity of a full client-server architecture.

Key Research Findings

1. Ratatui + WASM is Production-Ready

From the search results, several projects demonstrate this works:

• Ratzilla (1.2k GitHub stars): Official ratatui project for building terminal-themed web apps with WASM
• Webatui: Integration between Yew and Ratatui
• Multiple production websites using this stack

The approach is validated: write once in ratatui, compile to WASM with ratzilla, render in browser.

2. Zellij is Powerful but Limiting

Zellij’s WASM plugin system is innovative but:

• Requires Zellij (excludes tmux/screen users)
• Plugin runs in a pane (limited screen real estate)
• Can’t easily be standalone or web-deployed
• Better as a future integration than primary target

Verdict: Build standalone first, consider Zellij plugin as phase 2/3.

3. The Dual-Target Pattern is Emerging

Projects like Ratzilla show the pattern:

• Shared core logic (platform agnostic)
• Native backend (crossterm) for terminal
• Web backend (DOM rendering) for browser
• Same widgets, same code, different backends

Why This Architecture Wins

Compared to Web-First (React/Vue + API)

Compared to Pure Terminal

Compared to Zellij Plugin

The Stack Decision

Based on research:

Ratatui Ecosystem

• ratatui 0.29: Core TUI framework
• crossterm: Native terminal backend
• ratzilla 0.3: WebAssembly backend

These three share the same widget system. Your UI code works everywhere.

WASM Tooling

• trunk: Build tool (like cargo but for WASM)
• wasm-bindgen: Rust/JS bridge
• web-sys: Browser API access

Why Not Yew/Leptos/Dioxus?

Those are web frameworks. You’d write separate UI code for web vs terminal. With ratatui+ratzilla, the same widgets render to:

• Terminal escape codes (native)
• DOM elements (web)

This is the crucial difference that makes the dual-target approach feasible.

Addressing Concerns

“Is WASM in the browser really a good experience?”

Yes, based on evidence:

• Ratzilla demo loads instantly
• Terminal aesthetic is novel and appealing
• Works offline (PWA capable)
• Fast enough for chat interfaces

“What about server-side features?”

Future option: Add harness-server crate

• TUI can connect to local or remote server
• Enables multi-user, team features
• But not required for personal use

“How does code execution work in browser?”

Two approaches:

1. WASM sandbox: Tools compile to WASM, run in browser
2. No execution: Browser version read-only, use native for tools

Recommendation: Start with option 2, add option 1 later.

The Revised Plan

Immediate (Phase 1)

1. Build core logic with conditional compilation
2. Build native TUI with ratatui+crossterm
3. Polish terminal experience

Near-term (Phase 2)

1. Add ratzilla backend
2. Build web version with trunk
3. Add export/import for conversation sync

Future (Phase 3+)

1. Security hardening with wasmtime
2. Optional server mode
3. Optional Zellij plugin
4. Team collaboration features

What We Should Do Next

1. Validate the approach: Build a minimal prototype

   • Single conversation view
   • Send/receive messages
   • Native + WASM both working

2. Document the architecture: Add to existing docs

   • Update tech stack
   • Update roadmap
   • Add TUI-specific architecture doc ✓ (done)

3. Start with core crate:

   • Define shared types
   • Implement conversation logic
   • Add LLM provider trait

The research shows this is a solid, validated approach used by production projects. The ratatui ecosystem provides exactly what we need for dual-target deployment.