Bridge & IDE 集成
两个不同的系统。IDE 集成通过 localhost 上的 MCP 将 CLI 连接到同一台机器上的 VS Code 和 JetBrains。Bridge 将 CLI 实例连接到 claude.ai 作为 Web 前端，实现从任何浏览器的远程控制。
架构
IDE Integration (local)
Bridge (remote)
IDE 集成
支持的 IDE
Extension discovered and auto-installed via
code --install-extension anthropic.claude-code-vscode.
Communicates via MCP over SSE or WebSocket on localhost.
IntelliJ IDEA, WebStorm, PyCharm, PhpStorm, RubyMine, CLion, GoLand, Rider, DataGrip, DataSpell, AppCode, Android Studio, Aqua, RustRover, Writerside. Plugin must be installed manually.
发现机制如何工作
IDE 扩展在启动时将锁定文件写入 ~/.claude/ide/<ide-name>-<pid>.lock，
在关闭时删除它们。Claude Code 读取这些锁定文件以发现正在运行的 IDE 实例
及其连接信息（端口、传输类型、认证令牌）。
IDE MCP 传输类型
// SSE transport from IDE (read via EventSource)
{ type: 'sse-ide', url: 'http://localhost:PORT/sse', ideName: 'vscode' }
// WebSocket transport from IDE
{ type: 'ws-ide', url: 'ws://localhost:PORT/ws', ideName: 'vscode', authToken?: 'token' }These are internal transport types, not user-configurable. Set up automatically by the IDE extensions.
功能
File editing sync
When Claude Code edits a file, the IDE is notified via MCP. The IDE shows a diff view and the user can accept or reject changes in the editor.
Context sharing
The IDE can send selected text, open files, and cursor position to Claude Code, enriching its understanding of what the user is working on.
Diff views
openDiffInIde() opens a diff view in the IDE for a specific file. closeDiffTabsInIde() cleans up when changes are accepted.
Bidirectional channel (claude-vscode)
Special notification channel between CLI and VS Code. Sends file edits, feature gate values, analytics. Receives file changes and user actions.
Bridge 系统（远程控制）
Bridge 将 CLI 实例连接到 claude.ai 作为 Web 前端。用例：从任何浏览器控制 Claude Code、 在远程服务器上运行、管理多个会话、通过 QR 码和 URL 共享会话。
两种协议版本
| Version | Reading | Writing | Notes |
|---|---|---|---|
| v1 | WebSocket (WSS) | HTTP POST (batched every 100ms) | Environments API + poll loop. Older, more complex. |
| v2 | SSE stream | HTTP POST (CCRClient) | Direct session creation, simpler. Feature-gated. |
三种执行模式
| Mode | Entry point | Description |
|---|---|---|
| Standalone | claude remote-control / bridgeMain.ts | Dedicated process, supports multiple concurrent sessions |
| REPL In-Process | initReplBridge.ts → replBridge.ts | Bridge runs within an existing REPL session |
| Env-less | remoteBridgeCore.ts | Direct session connection (v2 protocol) |
生成模式（独立）
| Mode | Description |
|---|---|
| single-session | One session in CWD, bridge closes when done |
| worktree | Persistent server, each session gets an isolated git worktree |
| same-dir | Persistent server, all sessions share CWD |
通信协议
出站：CLI → claude.ai
| Type | Description |
|---|---|
| assistant | Claude's response text |
| result | Tool execution results |
| partial_assistant | Streaming partial responses |
| status | Status updates |
| control_response | Response to a control request |
| control_request | CLI-initiated control request |
| keep_alive | Keepalive ping |
入站：claude.ai → CLI
| Type | Description |
|---|---|
| user | User messages from the web UI |
| control_request | Server-initiated control request |
| control_response | Response to CLI's control request |
| keep_alive | Keepalive ping |
| update_environment_variables | Update env vars (token refresh) |
控制请求子类型（选定）
| Subtype | Direction | Description |
|---|---|---|
| initialize | Server → CLI | Initialize session, returns commands, models, account, PID |
| interrupt | Server → CLI | Interrupt current turn |
| can_use_tool | CLI → Server | Request permission to execute a tool (user sees Allow/Deny in browser) |
| set_model | Server → CLI | Change the AI model |
| set_permission_mode | Server → CLI | Change permission mode |
| mcp_set_servers | Server → CLI | Replace dynamic MCP servers |
| rewind_files | Server → CLI | Revert file changes |
| apply_flag_settings | Server → CLI | Apply feature flag settings from backend |
| elicitation | Server → CLI | Request user input for MCP elicitation |
会话生命周期
v1（环境 API + 轮询循环）
v2（直接会话）
权限流程（远程）
当 CLI 在远程运行时需要执行工具，它向服务器发送
can_use_tool 控制请求。
Web UI 向用户显示允许/拒绝对话框。响应还可以包含修改的工具输入或新的权限规则。
// Permission response from web UI
{
behavior: 'allow' | 'deny',
updatedInput?: Record<string, unknown>, // Modified tool args
updatedPermissions?: [ // New session rules
{ tool: 'Bash(rm:*)', behavior: 'deny' }
],
message?: string
}认证
OAuth 令牌解析顺序
- 1. CLAUDE_BRIDGE_OAUTH_TOKEN env var (dev only)
- 2. OAuth token from OS keychain
- 3. Interactive OAuth flow via browser
JWT 会话令牌刷新
- Refresh scheduled 5 min before JWT expiry
- Fallback: refresh every 30 min if JWT can't be decoded
- New token sent to child process via
update_environment_variables - Max 3 consecutive init failures before bridge is disabled
Every request includes: Authorization: Bearer <oauth_token>,
anthropic-version: 2023-06-01,
anthropic-beta: environments-2025-11-01.
For ELEVATED security tier: also X-Trusted-Device-Token.
常量和超时
| Constant | Value | Description |
|---|---|---|
| Poll interval (idle) | 2,000ms | v1: how often to check for new work |
| Poll interval (at capacity) | 600,000ms (10 min) | v1: poll interval when all slots are busy |
| SSE reconnect base delay | 1,000ms | v2: initial reconnection delay |
| SSE reconnect max delay | 30,000ms | v2: max reconnection backoff |
| SSE reconnect give-up | 600,000ms (10 min) | v2: stop reconnecting after this |
| SSE liveness timeout | 45,000ms | v2: max time without data before reconnect |
| HybridTransport batch flush | 100ms | v1: batch outgoing messages |
| HybridTransport POST timeout | 15,000ms | v1: HTTP POST timeout |
| Token refresh buffer | 5 min | Refresh JWT before expiry |
| Fallback refresh interval | 30 min | Refresh if can't decode JWT |
| Max init failures | 3 | Disable bridge after 3 consecutive failures |
| Bridge failure dismiss | 10,000ms | Auto-dismiss error UI |
| Session reclaim threshold | 5,000ms | Reclaim stale sessions older than this |
| Shutdown grace period | 30,000ms | SIGTERM → SIGKILL delay for child processes |
worktree 生成模式，
每个远程会话都有自己的隔离 git worktree，因此并行用户永远不会冲突。
can_use_tool 协议意味着 Web UI 获得完整的交互式权限提示，
包括在执行之前修改工具参数的能力。