Skip to main content
The bridge is a bidirectional communication layer that connects Claude Code’s CLI to IDE extensions. It allows the CLI to run as a backend for IDE-based interfaces, routing messages, permission prompts, and session state between the two sides. Source location: src/bridge/

​
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) │
                              └──────────────────────┘

​
Supported IDEs

VS Code

Full bridge support including diff display, file watching, and permission prompts rendered inside the editor.

JetBrains

Full bridge support for IntelliJ-based IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.).

​
Key files

FilePurpose
bridgeMain.tsMain bridge loop — starts and manages the bidirectional channel
bridgeMessaging.tsMessage protocol: serialization and deserialization of bridge messages
bridgePermissionCallbacks.tsRoutes permission prompts from the core to the IDE UI
bridgeApi.tsAPI surface exposed to the IDE extension
bridgeConfig.tsBridge configuration (ports, paths, flags)
replBridge.tsConnects the REPL session to the bridge channel
jwtUtils.tsJWT-based authentication between the CLI and the IDE extension
sessionRunner.tsManages bridge session execution lifecycle
createSession.tsCreates new bridge sessions on connection
trustedDevice.tsDevice trust verification
workSecret.tsWorkspace-scoped secrets for secure communication
inboundMessages.tsHandles messages arriving from the IDE
inboundAttachments.tsHandles file attachments sent from the IDE
types.tsTypeScript types for the bridge wire protocol

​
Authentication

The bridge uses JWT (JSON Web Tokens) for authentication between the CLI process and the IDE extension. Tokens are generated via jwtUtils.ts and validated on each message to prevent unauthorized access to the bridge channel.
Workspace-scoped secrets (workSecret.ts) ensure that bridge tokens are scoped to a specific workspace and cannot be reused across different projects.

​
Session management

Each IDE connection initiates a bridge session via createSession.ts. The session runner (sessionRunner.ts) manages the full lifecycle:
1

Connection

The IDE extension connects to the CLI bridge endpoint. JWT authentication is performed.
2

Session creation

A new session is created via createSession.ts, initializing the Query Engine and tool context.
3

Message routing

Inbound messages from the IDE (inboundMessages.ts) are dispatched to the core. Responses and permission prompts are routed back to the IDE via bridgePermissionCallbacks.ts.
4

Teardown

When the IDE disconnects, the session is cleaned up and all associated resources are released.

​
Feature flag

The bridge is gated behind the BRIDGE_MODE feature flag and is stripped from non-IDE builds. Standard CLI usage does not include bridge code.
Do not enable BRIDGE_MODE in production CLI builds. The bridge adds network-accessible endpoints that are not needed for terminal-only usage.

Build docs developers (and LLMs) love

Get started for freeTalk to us