Bridge System: Bidirectional Communication Architecture Between CLI and IDE

The Problem

Claude Code is both a standalone terminal tool and embeddable in VS Code and JetBrains. How does a single process serve two completely different interaction surfaces?

When you type the claude command in your terminal, a Node.js process starts, loads the REPL loop, and interacts with you via stdin/stdout. But when you click the Claude icon in VS Code's sidebar, or open a Remote Control session on claude.ai, the same CLI process is responding behind the scenes. This means:

• A Claude Code instance running in the terminal needs to synchronize messages in real time with a remote Web UI
• User actions on the Web UI (sending prompts, interrupting, switching models) need to be relayed to the local CLI process
• Permission requests need to traverse processes and networks, then wait for a response
• Session JWT tokens need automatic refresh to prevent long-running tasks from being interrupted by auth expiration
• File attachments need to be downloaded from the web to the local machine for the CLI process's tools to use

At the heart of all this is the Bridge system — a complete bidirectional communication architecture that treats the CLI process as the "backend" and the IDE extension or Web UI as the "frontend," enabling real-time interaction through polling, WebSocket, and SSE.

Architecture Overview

The Bridge system's architecture can be summarized in one sentence: the CLI process registers as an Environment, polls for Work Items, and communicates bidirectionally with Session Ingress via WebSocket/SSE.

The system has two operating modes:

1. Standalone Bridge mode (bridgeMain.ts): Launched by the claude remote-control command, it runs as a long-lived process that polls the server and forks a subprocess for each session. Supports concurrent multi-session and worktree isolation.
2. REPL-embedded Bridge mode (replBridge.ts): Automatically connects during interactive REPL execution, exposing the current session to the Web UI, enabling scenarios like "coding in the terminal while monitoring on your phone."

bridgeMain.ts: The Standalone Bridge Main Loop

bridgeMain.ts is the core of standalone Bridge mode. The runBridgeLoop function implements a complete poll-dispatch-manage loop responsible for: environment registration, work polling, session spawning, heartbeat maintenance, and error recovery.

BackoffConfig and Backoff Strategy

In networked environments, transient failures are the norm. The Bridge system defines fine-grained backoff configuration:

Backoff configuration is split into two categories: connection errors (conn*) and general errors (general*). Connection errors start at 2 seconds with a 2-minute cap and give up after 10 minutes; general errors start faster (500ms) with a 30-second cap. shutdownGraceMs controls the grace period from SIGTERM to SIGKILL (default 30 seconds), ensuring subprocesses have time to clean up.

Core Structure of the Main Loop

The runBridgeLoop function signature itself reveals the system's dependency injection design:

The function maintains numerous state Maps internally, and these data structures together form the core of session management:

Worth noting here is the existence of sessionCompatIds. CCR v2's infrastructure layer uses cse_*-prefixed IDs, while the claude.ai frontend and compatibility API use session_*-prefixed IDs. Both map to the same underlying UUID but require different formats at different API endpoints. sessionCompatIds is computed once at spawn time and cached, ensuring cleanup and state updates always use a consistent key.

Work Polling and Dispatch

The core of the main loop is a while (!loopSignal.aborted) loop, where each iteration queries for new work items via pollForWork:

When a session-type work item is received, the system needs to make a series of decisions:

For sessions that are already running, the system doesn't spawn a duplicate process. Instead, it passes the new access token to the existing subprocess — this is the critical path for JWT refresh. The server re-dispatches the work item before the JWT expires, carrying a new session_ingress_token, and Bridge injects the new token into the subprocess via existingHandle.updateAccessToken().

Heartbeat Mechanism

Heartbeats are critical for maintaining work leases. The heartbeatActiveWorkItems function iterates over all active sessions and sends heartbeats to the server:

Heartbeats return four states: ok (at least one success), auth_failed (JWT expired, reconnection triggered), fatal (environment doesn't exist), failed (all failed). The main loop decides the next step based on the heartbeat result: auth_failed triggers re-polling to obtain a new token, fatal may lead to environment reconstruction.

Capacity Management and Poll Cadence

The Bridge's polling frequency isn't fixed — it dynamically adjusts based on current state. PollIntervalConfig defines intervals across multiple dimensions:

These configurations are delivered in real time via GrowthBook, allowing the operations team to adjust global polling rates without releasing a new version. The pollConfig.ts code uses Zod schemas for strict configuration validation:

When all session slots are occupied, Bridge enters "full-capacity heartbeat mode": it stops polling for new work and only sends heartbeats to maintain leases. Once a session ends and frees a slot, the capacity wake mechanism immediately interrupts the sleep, letting Bridge resume polling:

Capacity Wake Mechanism

Capacity wake (capacityWake) is an elegant signal-merging primitive defined in capacityWake.ts:

The design concept: before entering "full-capacity sleep," call signal() to get a merged signal. This signal fires in three scenarios:

1. The outer loop is aborted (process shutdown)
2. The capacity controller is aborted (wake() is called)
3. The sleep timeout expires naturally

When a session ends, the onSessionDone callback calls capacityWake.wake(), immediately waking the main loop waiting in sleep(interval, cap.signal). wake() not only aborts the current controller but also creates a new one — ensuring the next loop iteration can sleep again. The cleanup() function removes event listeners, preventing listener accumulation on AbortSignal objects.

replBridge.ts and bridgeMain.ts use the exact same createCapacityWake primitive, eliminating the maintenance burden of two previously duplicated codebases.

bridgeMessaging.ts: The Message Protocol Layer

The message protocol layer is the Bridge system's "translator," responsible for: type determination, inbound routing, echo cancellation, and control request handling.

Type Guards and Message Filtering

The system defines strict type guards to distinguish different message types:

Not all REPL internal messages should be sent to Bridge. isEligibleBridgeMessage performs precise filtering:

Virtual messages (generated by internal REPL calls) are not sent — Bridge/SDK consumers see the summarized tool_use/result, not the intermediate process.

Inbound Message Routing and Echo Cancellation

handleIngressMessage is the single entry point for inbound messages, implementing a critical echo cancellation mechanism:

Why is echo cancellation needed? Because WebSocket is bidirectional — messages sent by the CLI may be broadcast back by the server. Without echo cancellation, a user message could be executed twice by the CLI. The system uses two independent BoundedUUIDSet instances: recentPostedUUIDs filters out self-sent messages, and recentInboundUUIDs filters duplicate inbound deliveries.

BoundedUUIDSet: Ring Buffer

The echo cancellation data structure isn't a simple Set<string> — it's a capacity-limited ring buffer:

This design guarantees constant memory usage at O(capacity). Messages are added in chronological order, and the oldest entries are always the ones evicted. The default capacity of 2000 far exceeds the actual echo window (echoes typically arrive within milliseconds).

Server Control Request Handling

The server can send control requests to the CLI (initialize, switch model, interrupt, set permission mode), and the CLI must respond within 10-14 seconds, or the server will disconnect the WebSocket:

Several notable design aspects in this code:

1. Outbound-only mode: When Bridge is only mirroring output (not accepting remote control), all mutable requests return errors — but initialize still returns success, because the server disconnects immediately when initialize fails.
2. Permission mode security boundary: set_permission_mode doesn't directly call transitionPermissionMode. Instead, it delegates the decision to the caller via a callback. This is because auto mode and bypassPermissions mode require additional security checks, and these checks' dependencies cannot be imported into the Bridge module (startup isolation constraint).

JWT Authentication System

Bridge authentication is based on short-lived JWTs (JSON Web Tokens). Each session's session_ingress_token has an expiration time, and the system needs to proactively refresh before expiration.

Token Decoding

jwtUtils.ts provides JWT decoding without signature verification — Bridge only needs to read the exp field to schedule refreshes; signature verification is done server-side:

createTokenRefreshScheduler: The Refresh Scheduler

The refresh scheduler is the core of the entire authentication system. It's a factory function that returns four methods: schedule, scheduleFromExpiresIn, cancel, and cancelAll:

The generation counter is an elegant concurrency control mechanism. Each call to schedule() or cancel() increments the generation number. The async doRefresh() checks whether the generation number has changed after await getAccessToken() returns:

Core parameters of the refresh strategy:

In bridgeMain.ts, the refresh scheduler selects different strategies based on session type:

The difference between v1 and v2 sessions is critical: v2 uses CCR's worker endpoints, which validate the session_id claim in the JWT — a generic OAuth token doesn't contain this claim, so v2 sessions need to go through reconnectSession to have the server re-dispatch with a new JWT.

bridgePermissionCallbacks.ts: Cross-Process Permission Callback Relay

In Bridge mode, permission decisions may happen remotely (the user clicks "Allow" or "Deny" in the claude.ai Web UI). The permission callback system defines the cross-process relay interface:

The design of this interface reflects several important considerations:

1. Request-response pattern: Each permission request has a unique requestId, sent via sendRequest and subscribed via onResponse. cancelRequest notifies the Web UI to withdraw the prompt when the CLI side cancels.

2. Modifiable input: updatedInput allows users to modify tool parameters during authorization (e.g., changing a file path), and updatedPermissions allows users to add persistent rules while authorizing ("always allow reading this directory").

3. Type-safe validation: The isBridgePermissionResponse type guard avoids the risks of as type assertions:

In standalone Bridge mode, sessionRunner.ts captures control_request (subtype: 'can_use_tool') from the subprocess's stdout, forwards it to the server, waits for the user's decision on the Web UI, then relays the response back through the subprocess's stdin.

sessionRunner.ts: Session Lifecycle

sessionRunner.ts handles the complete subprocess lifecycle: spawn, monitor, communicate, and clean up.

Subprocess Spawning

Several key decisions:

• CLAUDE_CODE_OAUTH_TOKEN: undefined explicitly clears the parent process's OAuth token, ensuring the subprocess uses CLAUDE_CODE_SESSION_ACCESS_TOKEN.
• --input-format stream-json and --output-format stream-json make the subprocess communicate in NDJSON format, one JSON object per line.
• --replay-user-messages has the subprocess replay user messages, used for extracting the first message text (for title derivation).
• All three stdio channels use 'pipe' mode: stdin for control instructions (token refresh, permission responses), stdout for NDJSON parsing, stderr for error diagnostics.

Activity Tracking

Every line of subprocess stdout output is parsed as an activity event:

A tool name-to-verb mapping table makes status displays more user-friendly:

Hot Token Update

The subprocess's updateAccessToken method injects a new token via stdin without restarting the subprocess:

When the subprocess's StructuredIO handler receives an update_environment_variables message, it directly modifies process.env, so the next call to getSessionIngressAuthToken() automatically picks up the new token.

replBridge.ts: Exposing REPL Sessions via Bridge

Unlike the standalone Bridge, the REPL-embedded Bridge doesn't spawn subprocesses — it connects directly to Session Ingress, bidirectionally syncing the current REPL's message stream to the Web UI.

initBridgeCore: The Startup Flow

initBridgeCore is the core initialization function for the REPL Bridge. It receives all external dependencies via dependency injection:

The initialization flow involves multiple steps:

1. Check crash recovery pointer: Read the bridgePointer file; if a prior session state exists and we're in perpetual mode, attempt recovery.
2. Register environment: Call registerBridgeEnvironment to register on the server.
3. Create or recover session: Perpetual mode attempts reconnectSession; otherwise creates a new session.
4. Write crash recovery pointer: Save current state for recovery after kill -9.
5. Start poll loop: Wait for the server to dispatch work items (user sends a message in the Web UI).

Environment Reconstruction Strategy

When polling returns 404 (environment reclaimed by the server), the system initiates an environment reconstruction flow, attempting two strategies:

Strategy 1 is "seamless recovery" — the URL the user sees on their phone doesn't change, session state (including previouslyFlushedUUIDs) is preserved, and history messages won't be resent. Strategy 2 is "degraded recovery" — the old session is archived, a new one is created, but context may be lost.

Concurrent reconstruction is guarded by a promise:

Bidirectional Message Sync

The REPL Bridge message flow is illustrated below:

sequenceDiagram
    participant User as User (Terminal/Web)
    participant REPL as REPL Loop
    participant Bridge as replBridge
    participant Transport as WebSocket/SSE
    participant Server as Session Ingress

    Note over User,Server: Outbound path: REPL -> Web UI
    REPL->>Bridge: writeMessages(messages)
    Bridge->>Bridge: Filter isEligibleBridgeMessage
    Bridge->>Bridge: Convert toSDKMessages
    Bridge->>Bridge: Filter previouslyFlushedUUIDs
    Bridge->>Transport: transport.write(sdkMsg)
    Transport->>Server: WebSocket/SSE POST

    Note over User,Server: Inbound path: Web UI -> REPL
    Server->>Transport: WebSocket message
    Transport->>Bridge: handleIngressMessage
    Bridge->>Bridge: Echo filter (BoundedUUIDSet)
    Bridge->>Bridge: Type check + routing
    Bridge->>REPL: onInboundMessage(sdkMsg)
    REPL->>REPL: Execute user request

    Note over User,Server: Control path
    Server->>Transport: control_request (interrupt/set_model)
    Transport->>Bridge: handleServerControlRequest
    Bridge->>REPL: onInterrupt() / onSetModel()
    Bridge->>Transport: control_response

Inbound Attachments: Files Flowing from Web to CLI

When a user uploads files or images on claude.ai, those attachments need to be delivered to the local CLI process. inboundAttachments.ts implements this flow:

The flow is:

1. The Web composer uploads the file to the Anthropic server, obtaining a file_uuid
2. The user message carries a file_attachments array
3. The CLI receives the inbound message and downloads the file from /api/oauth/files/{uuid}/content using the OAuth token
4. The file is written to the ~/.claude/uploads/{sessionId}/ directory
5. An @"filepath" reference prefix is added to the message text

prependPathRefs specifically handles multi-block content — references are added to the last text block, because processUserInputBase reads inputString from the end of processedBlocks:

This is an elegant fault-tolerant design — filenames use sanitizeFileName to prevent path traversal attacks, paths are wrapped in quotes to prevent parsing errors from spaces (@"path" rather than @path), and all network and IO operations are best-effort, with failures only skipping the attachment rather than interrupting message processing.

BRIDGE_MODE Feature Flag

The Bridge system's entry point is controlled by a compile-time feature flag. bridgeEnabled.ts defines multi-layered gating:

Here feature('BRIDGE_MODE') is a compile-time constant — in external builds, the true branch of the entire ternary expression is removed by dead-code elimination, including the GrowthBook string literals. This ensures:

• External builds: Bridge code is completely absent
• Internal builds: Two runtime conditions must be met
  • isClaudeAISubscriber() — excludes Bedrock/Vertex/Foundry and API key users
  • GrowthBook tengu_ccr_bridge gate — gradual rollout

The blocking version isBridgeEnabledBlocking is used for entry-point gating (the claude remote-control command), while the non-blocking version is used for UI rendering (whether the sidebar shows the Remote Control button).

More advanced gating also includes version checks:

This allows the operations team to force users to update without releasing a new version — simply raise tengu_bridge_min_version in GrowthBook.

Perpetual Mode

In normal mode, Bridge sessions end when the process exits. Perpetual mode allows sessions to survive across processes — after the CLI exits and restarts, it can resume the same Web session.

The implementation relies on the bridgePointer — a state pointer written to disk:

The pointer contains sessionId, environmentId, and source (distinguishing between REPL and standalone). When the CLI restarts:

1. Read the pointer file
2. Register the environment with reuseEnvironmentId (idempotent operation)
3. If registration returns the same environmentId, call reconnectSession to re-queue
4. If the environment has expired (returns a different ID), degrade to new session creation

A critical detail: when recovering sessions in perpetual mode, initialMessages are marked as already sent (added to previouslyFlushedUUIDs) to prevent duplicate messages from causing the server to disconnect the WebSocket. At the same time, lastTransportSequenceNum is restored from the previously saved value, letting the SSE connection resume from the breakpoint rather than replaying the full history.

SpawnMode: Multi-Session Management Strategy

The standalone Bridge supports three spawn modes, controlled by BridgeConfig.spawnMode:

worktree mode calls createAgentWorktree at spawn time:

After a session ends, onSessionDone automatically cleans up the worktree:

Note the use of trackCleanup — all cleanup operation Promises are tracked, and the shutdown sequence awaits their completion before calling process.exit(), preventing orphaned worktrees from being left behind.

System Sleep Detection

Long-running Bridge instances need to handle system sleep/wake events. When a laptop lid is closed, setTimeout and setInterval timers pause, and waking up may trigger a flood of backlogged callbacks. Bridge uses a simple yet effective detection method:

If the actual interval between two polls exceeds connCapMs * 2 (default 4 minutes), the system determines that a sleep occurred. At that point, error counters are reset — because the preceding timeouts weren't real network errors but artifacts of the system sleeping.

Design Summary

The Bridge system's architecture embodies several core design principles:

1. Dependency injection and startup isolation. initBridgeCore doesn't import commands.ts, config.ts, or any React components. All these dependencies are passed in as parameters. This allows the Agent SDK and Daemon to reuse the core logic without pulling in the REPL's full dependency tree (~1300 modules).

2. Best-effort degradation. Attachment download failures don't block message processing. Environment reconstruction failures don't crash the process. Token refresh failures have bounded retries. Every operation has a clear degradation path.

3. Idempotency and deduplication. Environment registration is idempotent (reuseEnvironmentId). Message sending is deduplicated via BoundedUUIDSet. Work acknowledgment (ack) failures don't lose work — the server will redeliver. completedWorkIds prevents already-completed work from being reprocessed.

4. Compile-time elimination. The ternary expression pattern with feature('BRIDGE_MODE') ensures external builds contain no Bridge code — not even the string literals of GrowthBook flags.