Skip to main content

ADR-165: WASM Split Architecture for Browser IDE

Status: Proposed Date: 2026-02-09 Author: Claude (Opus 4.6) Deciders: Hal Casteel, Engineering Team Tags: architecture, wasm, browser-ide, sidecar

Context​

CODITECT needs a browser-native IDE that runs AI-powered code editing in a web browser tab. The codestoryai/sidecar (Rust, 123K LOC, 410 files) provides the AI reasoning engine but cannot compile entirely to WASM due to OS-dependent dependencies (tokio full runtime, axum HTTP server, sqlx SQLite, openssl, gix for git, libc for PTY).

We must decide what runs in the browser (WASM) vs. what runs as a native process.

Decision​

Adopt a hybrid split architecture: thin WASM client in the browser for rendering and local code parsing, connected via WebSocket to the native sidecar binary running on localhost.

What Runs in Browser (WASM)​

ModuleSizePurpose
chunking/ (extracted)~200KBLanguage-aware code splitting
tree_printer/ (extracted)~50KBAST pretty-printing
repomap/graph (partial)~100KBCode graph construction/ranking
agentic/tool/type.rs (shared)~20KBTool type definitions
tree-sitter grammars~800KB eachSyntax parsing (lazy-loaded)

What Runs Native (Sidecar Binary)​

Everything else: LLM routing, MCTS planning, agent loop, session management, file I/O, git operations, terminal PTY, SQLite databases, MCP client.

Connection​

WebSocket on ws://localhost:42424/ws with MessagePack binary framing.

Alternatives Considered​

Alternative 1: Full WASM Compilation​

Replace all OS-dependent crates with WASM-compatible alternatives (e.g., reqwest with fetch API, SQLite with IndexedDB, custom git client).

Rejected because:

  • Months of porting effort for marginal benefit
  • Would lose PTY terminal capability entirely
  • WASM has no filesystem access for code editing
  • LLM API keys would be exposed in browser

Alternative 2: Full Server-Side Rendering​

Run everything server-side, browser is just a thin HTML renderer.

Rejected because:

  • High latency for every keystroke
  • Poor offline capability
  • Doesn't leverage browser's native rendering performance
  • Defeats the purpose of "IDE in browser"

Alternative 3: Theia IDE (Existing)​

Use the existing coditect-cloud-ide Theia 1.65 deployment.

Rejected as primary because:

  • Heavy: full Eclipse Theia framework (~200MB)
  • Slow startup time
  • Complex deployment (Node.js backend required)
  • Retained as enterprise/cloud option, not the lightweight local IDE

Consequences​

Positive​

  • WASM client loads in < 2 seconds, < 2MB gzipped
  • Local code parsing (tree-sitter WASM) eliminates round-trips for syntax highlighting
  • Sidecar binary reuses 100% of existing codestoryai code
  • PTY terminal works natively with full shell capabilities
  • LLM keys stay server-side, never exposed to browser

Negative​

  • Requires native sidecar binary installed on developer machine
  • Two processes to manage (sidecar + browser)
  • Module extraction requires maintaining fork of chunking/repomap code
  • WebSocket adds ~1-5ms latency to agent interactions

Risks​

  • AGPL-3.0 copyleft on sidecar: mitigated by process boundary (separate binary)
  • WASM bundle size growth: mitigated by lazy grammar loading
  • WebSocket reliability: mitigated by auto-reconnect with session persistence
  • SDD: docs/architecture/browser-ide/SDD-CODITECT-BROWSER-IDE.md
  • TDD: docs/architecture/browser-ide/TDD-CODITECT-BROWSER-IDE.md
  • ADR-166: WebSocket Protocol Design
  • ADR-167: Claude Code CLI Integration
  • ADR-168: Module Extraction from Sidecar
  • ADR-169: Browser Terminal Emulation