winfunc

Opcode Web Server Design

Design community intermediate

SOURCE https://github.com/winfunc/opcode

Description

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.

Installation

This entry records only its repository, not the path inside it, so there is no exact command to give. Open the source below and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

Repository README

This is the README for winfunc/opcode, shared by 2 entries in this directory. It describes the repository, not this entry specifically.

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:**

create_web_server() - Sets up Axum server with routes
claude_websocket_handler() - Manages WebSocket connections
execute_claude_command() / continue_claude_command() / resume_claude_command() - Execute Claude processes
find_claude_binary_web() - Locates Claude binary (bundled or system)

**Key Features:**

WebSocket Streaming: Real-time output from Claude processes
Session Management: Tracks active WebSocket sessions
Process Spawning: Launches Claude subprocesses with proper arguments
Comprehensive Logging: Detailed trace output for debugging

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:**

Handles both string payloads (Tauri) and object payloads (Web)
Maintains compatibility with existing UI components
Comprehensive error handling and logging

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