# PROP: Tauri Desktop Wrapper with Embedded Terminal

## Source
- **URL**: https://github.com/Tnze/tauri-plugin-pty (Tauri PTY plugin), https://github.com/marc2332/tauri-terminal (Tauri terminal demo), https://v2.tauri.app/develop/sidecar/ (Tauri sidecar pattern), https://github.com/marcomq/tauri-plugin-python (Python in Tauri)
- **Author**: Tnze (tauri-plugin-pty), marc2332 (tauri-terminal), Tauri team
- **Date**: 2025-2026

## Summary
Build a desktop application using Tauri v2 that wraps iEvo's Python backend and embeds a terminal widget (xterm.js) for native CLI passthrough. The Python backend runs as a sidecar process (bundled via PyInstaller) or as a local WebSocket server. The Tauri shell provides a modern desktop experience with custom UI panels (agent dashboard, pipeline view, file tree) alongside the embedded terminal. This is Phase 3 -- the current Textual TUI remains the primary interface for Phases 1-2.

## Relevance to iEvo
The Textual TUI is excellent for terminal users but cannot provide: system tray integration, native OS notifications, multi-window layouts, drag-and-drop file handling, or a polished onboarding experience for non-terminal users. A Tauri desktop wrapper adds these while keeping the terminal experience via xterm.js + PTY. Tauri's 2-5 MB binary size (vs Electron's 100-150 MB) aligns with the "lightweight orchestration layer" philosophy.

## Proposed Change

### 1. Architecture
```
Tauri v2 shell (Rust)
  +--- Frontend (Svelte/React)
  |     +--- xterm.js terminal widget (renders PTY output)
  |     +--- Agent dashboard panel (agent status, provider, model)
  |     +--- Pipeline view panel (spec -> plan -> code -> test progress)
  |     +--- File tree panel
  |     +--- Provider selector
  +--- tauri-plugin-pty (PTY management, spawns Claude Code / Codex)
  +--- Tauri IPC <-> Python backend
       |
       v
iEvo Python backend (sidecar or local WebSocket server)
  +--- Agent orchestration (core logic, unchanged)
  +--- implements IOAdapter protocol (DesktopAdapter)
  +--- Communicates with Tauri via IPC/WebSocket
```

### 2. Python backend integration
Two options (recommend Option B):

**Option A -- Sidecar:**
- Bundle Python backend as standalone executable via PyInstaller
- Tauri launches it as an external binary
- Communication via stdin/stdout JSON-RPC
- Pro: clean process isolation. Con: large bundle size (~50MB for Python runtime)

**Option B -- Local WebSocket server:**
- Python backend runs as `ievo --serve` (WebSocket server on localhost)
- Tauri frontend connects to WebSocket
- Pro: Python doesn't need bundling, user installs iEvo via pip/uv. Con: requires Python on user's machine
- Recommended for developer audience (who already have Python)

### 3. Terminal widget
- xterm.js renders terminal output from tauri-plugin-pty
- PTY spawns Claude Code / Codex CLI
- Full native terminal experience inside the desktop app
- Multiple terminal tabs (different agents, different providers)

### 4. Separate repository
`ievo-ai/ievo-desktop` -- keeps the desktop shell separate from the Python CLI. The CLI is the canonical backend; the desktop is a presentation layer.

## Affected Components
- New repo: `ievo-ai/ievo-desktop` (Tauri + Svelte/React frontend)
- New: `src/ievo/adapters/desktop_adapter.py` (WebSocket-based IOAdapter)
- New: `src/ievo/serve.py` (WebSocket server mode: `ievo --serve`)
- Modified: `src/ievo/cli.py` (add `--serve` flag)
- Dependencies: Tauri v2, xterm.js, tauri-plugin-pty (all in desktop repo)

## Scores
- Applicability: 3/5 (Phase 3 -- important but not urgent; TUI serves current users well)
- Effort: high (separate repo, Rust/TypeScript stack, cross-platform builds)
- Impact: UX (professional desktop experience, broader audience beyond terminal users)
