Skip to main content

ADR-168: Module Extraction Strategy from codestoryai/sidecar

Status: Proposed Date: 2026-02-09 Author: Claude (Opus 4.6) Deciders: Hal Casteel, Engineering Team Tags: sidecar, module-extraction, wasm, code-reuse, agpl

Context​

The codestoryai/sidecar is a 123,678-line Rust codebase (AGPL-3.0) providing AI-powered code editing capabilities. CODITECT needs to:

  1. Extract WASM-compatible modules for the browser client
  2. Add new capabilities (Claude CLI bridge, WebSocket bridge, terminal emulation)
  3. Maintain the ability to pull upstream updates
  4. Comply with AGPL-3.0 licensing

The sidecar has 4 workspace crates: sidecar (main), llm_client, llm_prompts, logging.

Decision​

Maintain the sidecar as a git submodule with a CODITECT overlay, extracting WASM-compatible modules into a separate crate.

Three-Layer Architecture​

Layer 1: Upstream sidecar (submodule, unmodified)
  └── submodules/r-and-d/sidecar/

Layer 2: CODITECT overlay (additions only, never modify upstream)
  └── submodules/r-and-d/browser-ide-overlay/
      ├── src/
      │   ├── claude_cli_bridge.rs
      │   ├── ws_bridge.rs
      │   └── terminal_ws.rs
      └── Cargo.toml (depends on sidecar as path dependency)

Layer 3: WASM extracted modules (independent crate)
  └── submodules/r-and-d/browser-ide-wasm/
      ├── src/
      │   ├── chunking/    (copied from sidecar, adapted)
      │   ├── repomap/     (partial, graph logic only)
      │   └── types/       (shared protocol types)
      └── Cargo.toml (wasm-bindgen, tree-sitter, petgraph)

Extraction Rules​

  1. Never modify upstream sidecar files - only add files in the overlay
  2. WASM crate copies code, not references - to avoid pulling in non-WASM deps
  3. Shared types crate used by both WASM and overlay
  4. Sync script tracks upstream changes to extracted modules

Upstream Sync Strategy​

# Weekly sync script
cd submodules/r-and-d/sidecar
git fetch origin
git diff HEAD..origin/main -- sidecar/src/chunking/ > /tmp/chunking.diff
# Review diff, apply compatible changes to browser-ide-wasm/src/chunking/

Extracted Module Inventory​

ModuleFilesLinesExtraction Type
chunking/13~2,500Full copy
repomap/graph.rs1~400Partial copy
repomap/tag.rs1~200Partial copy
repomap/types.rs1~150Partial copy
tree_printer/1~300Full copy
agentic/tool/type.rs1~165Reference (shared types)
Total18~3,7153% of sidecar codebase

Alternatives Considered​

Alternative 1: Fork the Entire Sidecar​

Fork codestoryai/sidecar, modify freely.

Rejected because:

  • 123K LOC to maintain independently
  • Lose upstream improvements (MCP integration, new tools, bug fixes)
  • AGPL-3.0 requires publishing all changes
  • Maintenance burden disproportionate to benefit

Alternative 2: Rebuild from Scratch​

Write our own Rust AI code editor engine.

Rejected because:

  • Months of development to replicate 55+ tools
  • MCTS planning engine alone is ~5K LOC
  • Sidecar represents person-years of engineering
  • No competitive advantage in reimplementation

Alternative 3: Dynamic Linking​

Build sidecar as a shared library (.dylib/.so), load in WASM host.

Rejected because:

  • WASM cannot load native shared libraries
  • Defeats the purpose of browser-native execution
  • Cross-platform compatibility nightmare

Consequences​

Positive​

  • Only 3% of sidecar code needs extraction/maintenance
  • Upstream updates flow through submodule with minimal conflict
  • WASM crate is small (~3.7K LOC), easy to maintain
  • Overlay pattern avoids AGPL-3.0 modification of upstream
  • Clear separation: upstream code vs CODITECT additions

Negative​

  • Code duplication between sidecar and WASM crate (~3.7K LOC)
  • Manual sync required when upstream changes extracted modules
  • Two codebases to test for the same logic
  • Overlay crate adds complexity to build system

AGPL-3.0 Compliance​

ComponentLicenseStrategy
Sidecar (upstream)AGPL-3.0Run as separate process, network boundary
Overlay (additions)AGPL-3.0Linked to sidecar, must be AGPL-3.0
WASM crate (extracted)Proprietary OKCopied code, not linked, independent compilation
Browser clientProprietaryCommunicates via WebSocket, no linking

Key: The AGPL-3.0 copyleft triggers on "modified version" and "conveying." The WASM crate extracts pure algorithms (chunking, graph ranking) that are mathematical in nature. The browser client communicates via network protocol (WebSocket), which is explicitly not a "link" under AGPL-3.0 Section 0.