Skip to main content
The bridge is a bidirectional communication layer connecting Claude Code’s CLI with IDE extensions (VS Code, JetBrains). It allows the CLI to run as a backend for IDE-based interfaces. The bridge lives in src/bridge/ and is gated behind the BRIDGE_MODE feature flag — it is stripped entirely from non-IDE builds.

​
Architecture

┌──────────────────┐         ┌──────────────────────┐
│   IDE Extension  │◄───────►│   Bridge Layer       │
│  (VS Code, JB)   │  JWT    │  (src/bridge/)       │
│                  │  Auth   │                      │
│  - UI rendering  │         │  - Session mgmt      │
│  - File watching │         │  - Message routing   │
│  - Diff display  │         │  - Permission proxy  │
└──────────────────┘         └──────────┬───────────┘
                                        │
                                        ▼
                              ┌──────────────────────┐
                              │   Claude Code Core   │
                              │  (QueryEngine, Tools)│
                              └──────────────────────┘
The IDE extension handles UI concerns (rendering, file watching, diff display) while the CLI handles all AI and tool execution. The bridge layer routes messages between them and proxies permission prompts back to the IDE.

​
Key files

Main bridge loop. Starts the bidirectional channel between the IDE extension and the Claude Code core. This is the entry point for bridge mode execution.
Message protocol implementation — serialization and deserialization of all messages exchanged between the IDE and CLI.
Routes permission prompts from Claude Code’s permission system to the IDE, so the user is prompted via the IDE UI rather than the terminal.
The API surface exposed to the IDE extension. Defines what the IDE can call on the CLI backend.
Connects the active REPL session to the bridge channel, wiring the interactive session into the bidirectional protocol.
JWT-based authentication utilities. The CLI and IDE extension exchange signed tokens to verify each other’s identity before any messages are processed.
Manages the lifecycle of a bridge session — creation, execution, and teardown.
Creates new bridge sessions, initializing the state and channel for a fresh IDE connection.
Device trust verification. Ensures the IDE extension connecting to the CLI is on a recognized, trusted device.
Workspace-scoped secrets used as part of the authentication handshake between the CLI and IDE.
Handles messages arriving from the IDE, dispatching them to the appropriate handlers in the CLI core.
Handles file attachments sent from the IDE to the CLI (for example, files dragged into the IDE chat interface).

​
Authentication

The bridge uses JWT-based authentication to secure the channel between the IDE extension and the CLI backend.
1

Session secret is established

When the CLI starts in bridge mode, it generates a workspace-scoped secret via workSecret.ts.
2

IDE extension authenticates

The IDE extension presents its credentials. jwtUtils.ts validates the JWT and confirms the device is trusted via trustedDevice.ts.
3

Secure channel opens

Once both sides are authenticated, the bidirectional message channel in bridgeMain.ts begins processing messages.

​
Permission proxying

When a tool requires user approval in bridge mode, the permission prompt is not shown in the terminal. Instead, bridgePermissionCallbacks.ts forwards the prompt to the IDE, where the user approves or denies via the IDE’s native UI.
The same permission rules and modes (default, plan, bypassPermissions, auto) apply in bridge mode. The only difference is where the prompt appears.

​
Feature flag

The bridge is controlled by the BRIDGE_MODE feature flag using Bun’s dead-code elimination: 
import { feature } from 'bun:bundle'

if (feature('BRIDGE_MODE')) {
  // All bridge code is only included in IDE builds
  const bridge = require('./bridge/bridgeMain.js')
}
This means the entire src/bridge/ directory is absent from standard CLI builds, keeping the binary lean for non-IDE usage.

Build docs developers (and LLMs) love

Get started for freeTalk to us