07-bridge-remote

Inkdown

Start writing

Shared from "Claude-Code" on Inkdown

Bridge & Remote Control

How Claude Code sessions can be controlled from the web (claude.ai/code) and mobile app.

What Is the Bridge?

The bridge system turns a locally-running Claude Code session into a remotely accessible experience. You can:

Start a session on your laptop
Open claude.ai/code in your browser
Watch and interact with the same session in real-time
Do the same from the Claude mobile app

Two Operational Modes

1. Standalone Bridge (`claude remote-control`)

Runs as a persistent server that:

Plain text

claude remote-control              # Single session mode
claude remote-control --capacity 8  # Multi-session, same directory
claude remote-control --worktree    # Multi-session, isolated worktrees

Plain text

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Mobile App  │     │  claude.ai   │     │   Server     │
│              │     │  /code       │     │              │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                   │                    │
       └───────────────────┼────────────────────┘
                           │
                    Work Items (Redis stream)
                           │
       ┌───────────────────▼────────────────────┐
       │          Bridge Instance               │
       │                                        │
       │  ┌──────────┐    ┌──────────────────┐  │
       │  │ Poll     │───▶│ Session Spawner  │  │
       │  │ Loop     │    │ (child process)  │  │
       │  └──────────┘    └────────┬─────────┘  │
       │                           │            │
       │  ┌────────────────────────▼─────────┐  │
       │  │    Transport (WS or SSE)         │  │
       │  │                                  │  │
       │  │  ┌──────────┐  ┌──────────────┐  │  │
       │  │  │ Messages │  │ Control      │  │  │
       │  │  │ (user)   │  │ (set_model,  │  │  │
       │  │  │          │  │  interrupt)  │  │  │
       │  │  └──────────┘  └──────────────┘  │  │
       │  └──────────────────────────────────┘  │
       └────────────────────────────────────────┘
                           │
                    NDJSON (stream-json)
                           │
       ┌───────────────────▼────────────────────┐
       │        Claude Code Child Process       │
       │        (--print --sdk-url ...)         │
       │                                        │
       │  ┌──────────────────────────────────┐  │
       │  │  Query Engine → Tools → API      │  │
       │  └──────────────────────────────────┘  │
       └────────────────────────────────────────┘

TypeScript

// Registration
POST /v1/environments
→ { environment_id, environment_secret }

// The environment has:
// - maxSessions: how many concurrent sessions
// - spawnMode: 'single-session' | 'same-dir' | 'worktree'
// - TTL: how long it lives without heartbeat

TypeScript

type WorkSecret = {
  session_ingress_token: string  // JWT for auth
  api_base_url: string
  use_code_sessions: boolean     // v2 vs v1 transport
  sources: string[]
  auth: { type: string, token: string }
  environment_variables: Record<string, string>
  mcp_config: McpConfig
}

TypeScript

interface SessionHandle {
  done: Promise<'completed' | 'failed' | 'interrupted'>
  kill(): void
  forceKill(): void
  writeStdin(message: string): void
  updateAccessToken(token: string): void
  activities: ActivityRingBuffer
  currentActivity: Activity | null
}

Subtype	Purpose
`initialize`	Session lifecycle handshake
`set_model`	Change the AI model
`set_max_thinking_tokens`	Adjust thinking budget
`set_permission_mode`	Change permission mode
`interrupt`	Interrupt current turn

TypeScript

const handle = await initBridgeCore({
  createSession,        // How to create a session
  wireTransport,        // How to wire up transport
  onInboundMessage,     // Handle incoming messages
  onPermissionResponse, // Handle permission responses
  onControlRequest,     // Handle control requests
  onStateChange,        // State change notifications
  perpetual,            // Crash recovery mode
  crashRecoveryPointer  // Path to pointer file
})

Mode	Behavior
`single-session`	One session, bridge exits when done
`same-dir`	Persistent server, all sessions share directory
`worktree`	Persistent server, each session gets isolated worktree

Plain text

while (true) {
  if (activeSessions.size >= capacity) {
    // Heartbeat-only mode (no new work polling)
    await heartbeatActiveWork()
    await waitForCapacityWake()  // Signal when session completes
  } else {
    const work = await pollForWork()
    if (work) spawnSession(work)
  }
}

Plain text

SIGTERM received
    │
    ▼
Stop polling for new work
    │
    ▼
Send SIGTERM to all child sessions
    │
    ▼
Wait 30 seconds (grace period)
    │
    ▼
SIGKILL stragglers
    │
    ▼
Archive sessions, deregister environment
    │
    ▼
Exit

File	Purpose
`src/bridge/bridgeMain.ts`	Standalone bridge server
`src/bridge/replBridge.ts`	REPL bridge (existing session)
`src/bridge/bridgeConfig.ts`	Auth/URL resolution
`src/bridge/bridgeMessaging.ts`	Message parsing and routing
`src/bridge/createSession.ts`	Session API client
`src/bridge/sessionRunner.ts`	Session spawner
`src/bridge/types.ts`	Shared type definitions
`src/bridge/flushGate.ts`	Flush gate mechanism
`src/bridge/capacityWake.ts`	Capacity wake signals
`src/bridge/workSecret.ts`	Work secret decoding
`src/bridge/jwtUtils.ts`	JWT utilities
`src/bridge/trustedDevice.ts`	Trusted device management
`src/bridge/pollConfig.ts`	Poll configuration
`src/bridge/replBridgeTransport.ts`	REPL bridge transport wiring
`src/bridge/replBridgeHandle.ts`	REPL bridge handle API
`src/remote/`	Remote session management
`src/server/`	Direct connect server

07-bridge-remote

Bridge & Remote Control

What Is the Bridge?

Two Operational Modes

1. Standalone Bridge (claude remote-control)

07-bridge-remote

Bridge & Remote Control

What Is the Bridge?

Two Operational Modes

1. Standalone Bridge (claude remote-control)

2. REPL Bridge (/remote-control)

Architecture

Core Concepts

Environment

Session

Work Item

Work Secret

Transport Versions

v1 — Session Ingress (WebSocket)

v2 — CCR (Server-Sent Events)

Session Spawning

Session Handle

Activity Tracking

Messaging Protocol

SDK Messages (User → Session)

Control Requests (Server → Session)

Control Responses (Session → Server)

Echo Deduplication

Flush Gate

Keep-Alive

REPL Bridge Details

Initialization

Crash Recovery

Reconnection Strategy

State Machine

Multi-Session Architecture

Spawn Modes

Capacity Management

Token Refresh

Graceful Shutdown

Key Files Reference

1. Standalone Bridge (`claude remote-control`)

1. Standalone Bridge (`claude remote-control`)

2. REPL Bridge (`/remote-control`)