Opcode Web Server Design

Opcode Web Server Design

This document describes the implementation of Opcode's web server mode, which allows access to Claude Code from mobile devices and browsers while maintaining full functionality.

Overview

The web server provides a REST API and WebSocket interface that mirrors the Tauri desktop app's functionality, enabling phone/browser access to Claude Code sessions.

Architecture

┌─────────────────┐    WebSocket     ┌─────────────────┐    Process     ┌─────────────────┐
│   Browser UI    │ ←──────────────→ │  Rust Backend   │ ────────────→  │  Claude Binary  │
│                 │    REST API      │   (Axum Server) │               │                 │
│ • React/TS      │ ←──────────────→ │                 │               │ • claude-code   │
│ • WebSocket     │                  │ • Session Mgmt  │               │ • Subprocess    │
│ • DOM Events    │                  │ • Process Spawn │               │ • Stream Output │
└─────────────────┘                  └─────────────────┘               └─────────────────┘

Key Components

1. Rust Web Server (`src-tauri/src/web_server.rs`)

**Main Functions:**

undefined

**Key Features:**

undefined

2. Frontend Event Handling (`src/components/ClaudeCodeSession.tsx`)

**Dual Mode Support:**

const listen = tauriListen || ((eventName: string, callback: (event: any) => void) => {
  // Web mode: Use DOM events
  const domEventHandler = (event: any) => {
    callback({ payload: event.detail });
  };
  window.addEventListener(eventName, domEventHandler);
  return Promise.resolve(() => window.removeEventListener(eventName, domEventHandler));
});

**Message Processing:**

undefined

3. WebSocket Communication (`src/lib/apiAdapter.ts`)

**Request Format:**

{
  "command_type": "execute|continue|resume",
  "project_path": "/path/to/project",
  "prompt": "user prompt",
  "model": "sonnet|opus",
  "session_id": "uuid-for-resume"
}

**Response Format:**

{
  "type": "start|output|completion|error",
  "content": "parsed Claude message",
  "message": "status message",
  "status": "success|error"
}

Message Flow

1. Prompt Submission

Browser → WebSocket Request → Rust Backend → Claude Process

2. Streaming Response

Claude Process → Ru