Bridge Remote Control

Advanced Guide · 16 min read

✓Based on source code analysis

What is Bridge?

Bridge is Claude Code's remote control backbone, enabling CLI instances to be remotely manipulated by external systems (desktop apps, web interfaces, CI/CD, Agent SDKs).

Three-Generation Architecture

Gen 1: HTTP Polling

Clients periodically poll server for new work instructions. Simple but high latency.

Gen 2: WebSocket REPL Bridge

Current main solution. Bidirectional WebSocket communication for real-time messaging.

Gen 3: Direct Connect

Direct WebSocket connections using NDJSON (newline-delimited JSON) protocol for local clients.

Starting Bridge Mode

claude bridge

Or with spawn mode for persistent server:

claude bridge --spawn --capacity 5

Spawn Modes

  • single-session - Current directory, closes after session
  • worktree - Persistent, each session uses isolated Git worktree
  • same-dir - Persistent, all sessions share working directory

JWT Authentication

Bridge uses Work Secret containing:

  • session_ingress_token - WebSocket auth JWT
  • api_base_url - API endpoint
  • mcp_config - MCP configuration
  • environment_variables - Environment settings

JWT auto-refreshes 5 minutes before expiration.

Remote Session Manager

Connect to remote Bridge sessions:

claude remote [sessionId]

viewerOnly mode: Observe Agent activity without intervention (useful for team collaboration).

Permission Bridging

Remote session permission requests forwarded to user endpoint:

{
  "behavior": "allow",
  "updatedInput": { "path": "/safe/path" }
}

Users can modify tool parameters when approving.

Direct Connect (NDJSON)

For local desktop app integration:

// Messages are newline-delimited JSON
{"type":"control_request","id":"123",...}
{"type":"streamlined_text","content":"..."}

Fault Tolerance

  • Connection: Exponential backoff (2s→4s→8s→...→120s)
  • Session: Timeout watchdog
  • Work: stopWorkWithRetry (1s→2s→4s)
  • System: SIGTERM → 30s graceful → SIGKILL
💡 Pro Tip: See Bridge Reference for complete source code analysis.