bridge — Remote Control Integration

Remote Control Integration

Connects local Claude Code instances to claude.ai cloud sessions. Handles JWT-based authentication, permission delegation to cloud, WebSocket transport for real-time messaging, and session compatibility negotiation.

Files

13k

Lines

JWT

Auth

TypeScript

🔵 claude.ai Bridge 🟢 JWT Auth 🟡 WebSocket 🔴 Permission Delegation

📚 What is this?

The bridge module is the secure tunnel between a local Claude Code REPL and the claude.ai cloud platform. It negotiates authentication, relays commands and responses over WebSockets, and delegates permission decisions back to the cloud when the local user grants remote control.

💡 Analogy

Think of the bridge as an embassy between two countries. The JWT token is the diplomatic passport, the WebSocket is the secure phone line, permission callbacks are the consular approvals for sensitive actions, and session compatibility is the protocol ensuring both sides speak the same language version.

Architecture

flowchart LR
  subgraph Local["Local Claude Code"]
    REPL["REPL Session"]
    RB["replBridge.tsx"]
    PC["bridgePermissionCallbacks"]
  end
  subgraph Transport["Transport Layer"]
    WS["WebSocket Client"]
    JWT["jwtUtils.ts"]
  end
  subgraph Cloud["claude.ai Cloud"]
    API["bridgeApi.ts"]
    CSA["codeSessionApi.ts"]
    RS["Remote Session"]
  end
  REPL --> RB
  RB --> WS
  WS --> API
  API --> RS
  RS --> CSA
  JWT --> WS
  PC --> RB
  RS -->|permission request| PC

Data Flow

flowchart TD
  USER["Cloud User Action"] --> CSA["codeSessionApi"]
  CSA --> MSG["JSON Message"]
  MSG --> WS["WebSocket Transport"]
  WS --> JWT["JWT Verify"]
  JWT --> RB["replBridge"]
  RB --> PERM{"Permission\nRequired?"}
  PERM -->|yes| PC["bridgePermissionCallbacks"]
  PC --> APPROVE["User Approve/Deny"]
  APPROVE --> RB
  PERM -->|no| EXEC["Execute Command"]
  RB --> EXEC
  EXEC --> RESP["Response Payload"]
  RESP --> WS

🚶 Step-by-Step Walkthrough: Remote command execution

Trace a command from claude.ai to local execution and back:

Cloud user — Sends a command through the claude.ai web interface.
codeSessionApi — Serializes the command into a JSON envelope with session metadata.
WebSocket — Transmits the envelope over an encrypted WebSocket connection.
jwtUtils.parseToken() — Validates the JWT signature and checks expiration/claims.
replBridge — Deserializes the message and routes it to the appropriate handler.
Permission check — If the command requires elevated access, bridgePermissionCallbacks prompts locally.
Local execution — The REPL processes the command (file edit, shell command, etc.).
Response relay — Results are serialized and sent back over the WebSocket to the cloud.
Session sync — Session state is reconciled between local and cloud representations.
Cloud render — The claude.ai interface displays the command output to the remote user.

Key Classes & Functions

Symbol	File	Purpose
`BridgeApi`	bridgeApi.ts	HTTP client for claude.ai REST endpoints
`ReplBridge`	replBridge.tsx	React component managing bridge connection state
`bridgePermissionCallbacks`	bridgePermissionCallbacks.ts	Callback registry for remote permission prompts
`parseJwt()`	jwtUtils.ts	Decodes and validates JWT tokens from cloud
`refreshToken()`	jwtUtils.ts	Handles JWT refresh before expiration
`CodeSessionApi`	codeSessionApi.ts	Session CRUD operations against cloud API
`createWebSocket()`	wsTransport.ts	WebSocket factory with auto-reconnect and backoff
`serializeMessage()`	protocol.ts	JSON envelope serializer for bridge protocol
`deserializeMessage()`	protocol.ts	Message parser with schema validation
`SessionCompatibility`	compatibility.ts	Version negotiation between local and cloud sessions
`BridgeEventEmitter`	events.ts	Typed event bus for bridge lifecycle events
`handleDisconnect()`	reconnect.ts	Graceful disconnect with state preservation

Directory Map

Source tree for bridge

bridge/
├── bridgeApi.ts                 ← HTTP client for cloud REST APIs
├── replBridge.tsx               ← Connection state React component
├── bridgePermissionCallbacks.ts ← Remote permission prompt handlers
├── jwtUtils.ts                  ← JWT decode, validate, refresh
├── codeSessionApi.ts            ← Cloud session CRUD
├── wsTransport.ts               ← WebSocket factory with reconnect
├── protocol.ts                  ← Message serialization/deserialization
├── compatibility.ts             ← Version negotiation logic
├── events.ts                    ← Typed event emitter for lifecycle
├── reconnect.ts                 ← Disconnect handling, state persist
├── types.ts                     ← Shared TypeScript interfaces
├── __tests__/
│   ├── bridgeApi.test.ts
│   ├── jwtUtils.test.ts
│   ├── wsTransport.test.ts
│   └── protocol.test.ts
└── index.ts                     ← Barrel export

Configuration

Option	Default	Description
`BRIDGE_WS_URL`	`wss://claude.ai/bridge`	WebSocket endpoint for bridge connections
`JWT_REFRESH_MARGIN_MS`	`60000`	Refresh token this many ms before expiry
`WS_RECONNECT_MAX_RETRIES`	`10`	Max reconnection attempts before giving up
`WS_RECONNECT_BACKOFF_MS`	`1000`	Base delay for exponential backoff reconnect
`PERMISSION_TIMEOUT_MS`	`30000`	Timeout for local permission prompt before auto-deny