How Claude Code Bridges IDEs: Local IPC Meets Remote WebSocket

What the Bridge Solves

Claude Code needs a way for an IDE plugin (VS Code or JetBrains) to keep the editor in sync with a CLI process and for a web page (claude.ai) to control the same CLI remotely. The solution is a set of two independent communication subsystems that share a common authentication and messaging protocol.

Two Bridge Scenarios

Local IDE bridge uses Unix domain sockets or stdio for intra‑machine IPC, giving sub‑millisecond latency and no network exposure.

Remote REPL bridge runs the CLI as a “Worker” that connects to Anthropic’s cloud (CCR). The web page talks to the cloud, which forwards commands over WebSocket (with SSE and polling as fallbacks).

Local IDE Bridge – Worker Types and Spawn Modes

The source defines three WorkerType values:

type WorkerType =
  | "claude_code"               // main CLI worker
  | "claude_code_assistant"    // assistant tab worker

Three SpawnMode options control how multiple sessions coexist: single-session: only one active CLI per machine (default). worktree: each Git worktree gets its own isolated Claude instance. same-dir: reuse the existing session when the web UI opens an already‑running CLI.

Concurrency is capped at 32 sessions by a GrowthBook feature flag; the limit is chosen to balance server load and team‑collaboration needs. Session timeout defaults to 24 hours, reflecting typical developer work‑day patterns.

Remote Bridge – Three‑Layer Transport Downgrade

The remote side implements a HybridTransport that automatically falls back from WebSocket → Server‑Sent Events → HTTP polling.

class rI6 { // WebSocketTransport
  url: URL;
  state: "idle" | "reconnecting" | "connected" | "closing" | "closed";
  reconnectAttempts = 0;
  reconnectStartTime: number | null = null;
  async connect() { /* try Bun WebSocket, then Node.js ws */ }
  handleConnectionError(closeCode?: number) { /* exponential back‑off, 10‑minute budget */ }
}

Reconnection has three clever parts:

Sleep detection – if the gap between attempts exceeds ~5 minutes, the whole budget is reset (handles laptop lid‑close).

Token‑refresh on close code 4003 – tries an OAuth refresh before giving up.

Message buffering – unsent messages are kept in messageBuffer; after reconnection the client sends X-Last-Request-Id so the server can replay any unacknowledged frames.

SSE Transport – Single‑Direction Push

SSE is used when a proxy blocks WebSocket. It sends data only from server to client; client‑to‑server messages are posted via HTTP.

class m_6 { // SSETransport
  url: URL;
  postUrl: URL; // POST endpoint (stream URL without /stream)
  lastSequenceNum = 0;
  seenSequenceNums = new Set<number>();
  async readStream(body: ReadableStream) { /* deduplicate frames */ }
  async write(payload: object) { /* up to 10 retries, exponential back‑off, abort on 4xx except 429 */ }
}

SSE includes a liveness timer: if no frame arrives for 45 seconds the client proactively disconnects, which is faster than waiting for TCP timeout.

Four‑Layer Authentication

The remote bridge stacks four credential layers:

Layer 1 – OAuth bearer token for API calls.

Layer 2 – Trusted device token to avoid repeated OAuth flows.

Layer 3 – Session ingress token that isolates each REPL session.

Layer 4 – Short‑lived JWT for sensitive operations.

This depth implements classic defense‑in‑depth: compromising one layer does not grant full access.

FlushGate – Ensuring Message Order Without ACK

class FlushGate {
  private pendingFlushes: Promise<void>[] = [];
  async acquire(): Promise<FlushGateHandle> { /* returns a handle that pushes its promise */ }
  async waitForAll(): Promise<void> { await Promise.all(this.pendingFlushes); }
}

// usage example
const gate = await flushGate.acquire();
try {
  await executeGitCommit();
  await sendStatusMessage("commit success");
} finally {
  gate.release();
  await flushGate.waitForAll(); // guarantees delivery to transport layer
}

FlushGate prevents out‑of‑order or lost status updates when a CLI finishes a git operation and immediately sends a result back to the web UI.

REPL Bridge Lifecycle Management

The store tracks four boolean flags ( replBridgeConnected, replBridgeExplicit, replBridgeReconnecting, replBridgeEnabled) whose conjunction defines an “active bridge” state shown in the UI.

Bridge events (e.g., bridge_repl_v2_transport_connected, bridge_repl_v2_session_created, bridge_repl_v2_jwt_refresh_failed) act as live documentation of the state machine, enabling precise observability.

Local Service Discovery – bridge‑pointer.json

The CLI writes ~/.claude/bridge-pointer.json containing pid, socketPath, version, and startedAt. The IDE extension polls this file, extracts the Unix socket path, and opens the IPC channel. This mirrors the Language Server Protocol’s file‑based discovery.

Design Insights from the Bridge

Transport and business logic are fully decoupled; all transports implement the same setOnData/write/close interface, making testing trivial.

Reconnection is driven by a time budget (10 minutes) rather than a fixed retry count, matching real‑world network jitter patterns.

Optimistic execution with “eventual consistency” – FlushGate waits only for the transport layer, not for ACKs, reducing perceived latency.

Telemetry strings double as state‑machine documentation, eliminating separate docs.

Critique – Costs of the Design

The bridge lives in src/bridge/ with 31 files, spanning OAuth, JWT, WebSocket, SSE, Unix sockets, and feature‑flag logic, creating a steep onboarding curve.

The overloaded term “Bridge” refers to two very different components; clearer names like IDEConnector and RemoteBridge would improve readability.

GrowthBook‑controlled concurrency means that in test environments without the flag the 32‑session path cannot be exercised, increasing test complexity.

Practical Takeaways for Your Own Agent Project

Replace fixed retry counts with a reconnection budget and exponential back‑off (see code snippet).

Use a simple JSON pointer file for local service registration instead of dynamic port allocation.

Define state‑machine transitions as constant telemetry strings so monitoring data serves as live documentation.

Conclusion – Six Bold Takeaways

Two distinct systems serve local IDE (UDS/IPC) and remote REPL (WebSocket → SSE → polling) scenarios.

Three‑layer transport downgrade guarantees operation in almost any network environment.

Time‑budget reconnection outperforms a fixed‑retry strategy.

FlushGate provides a lightweight ordering guarantee without waiting for ACKs.

Four‑layer authentication addresses security at progressively finer granularity.

Telemetry event names act as self‑documenting state‑machine specifications.