Bridge System
- Entity ID:
ent-20260409-1c992050d796 - Type:
service - Scope:
shared - Status:
active - Aliases: bridge, bridgeMain.ts, IDE integration
Description
The Bridge System is the bidirectional communication layer that connects IDE extensions (VS Code, JetBrains) with the Claude Code CLI process. Rather than building separate agent implementations for each IDE, Anthropic chose to run the same queryengine-ts engine underneath all interfaces, with the bridge abstracting away transport differences. This means the terminal CLI, VS Code extension, and JetBrains plugin all share identical agent logic, tool execution, and permission-pipeline enforcement.
Transport Versions
The bridge has evolved through two transport generations:
| Version | Transport | Characteristics |
|---|---|---|
| v1 | stdin/stdout JSON-RPC | Simple pipe-based protocol; the IDE spawns the CLI as a child process and communicates via newline-delimited JSON on stdio |
| v2 | WebSocket | Persistent bidirectional connection; supports reconnection, multiplexed channels, and higher throughput for streaming responses |
The active transport version is selected based on the IDE extension's capabilities and is negotiated during the handshake phase. Both versions carry the same message schema, so the upper layers of the system are transport-agnostic.
Authentication
Bridge sessions are authenticated via JWT tokens issued by the IDE extension. The token encodes the user's Anthropic API credentials, workspace context, and permitted scopes. The CLI validates the JWT signature before accepting any bridge commands, preventing unauthorized processes from hijacking an active agent session.
BRIDGE_MODE Flag
When Claude Code detects it is running as a bridge backend (rather than as an interactive terminal), it sets the BRIDGE_MODE environment flag. This flag triggers several behavioral changes:
- The terminal-renderer is disabled; output is serialized as structured JSON instead of ANSI escape sequences.
- Interactive permission prompts are replaced with structured permission request messages that the IDE can render in its own UI.
- The hooks-system fires bridge-specific lifecycle events so that IDE extensions can react to tool executions.
- The skill-system and plugin-system remain available, so IDE users have access to the same extensibility as terminal users.
Bidirectional Messaging
Communication is fully bidirectional. The IDE can send user messages, cancel requests, and push workspace context updates (e.g., active file changed, selection changed). The CLI sends back streaming assistant responses, tool invocation notifications, permission requests, and telemetry events. This two-way flow enables features like inline diff previews in VS Code that would be impossible with a one-way pipe.
Key claims
clm-20260409-f48ec11055cd: QueryEngine.ts is ~46K lines -- the core LLM API engine handling streaming, tool execution, and session management.
Relations
rel-20260409-1fd4818e: ent-20260409-1c992050d796 --[uses]--> ent-20260409-bd96ad1d4b2arel-20260409-b5fdd0f9: ent-20260409-1c992050d796 --[uses]--> ent-20260409-4101f160d0c8
Sources
src-20260409-e7da1a492842