Claude IDE Bridge

Claude Code, but with your IDE's eyes.

A WebSocket bridge that connects Claude Code to VS Code (and Windsurf, Cursor) so Claude can see what your IDE sees: live diagnostics, go-to-definition, find references, hover types, open files, breakpoints, debugger state. Not file access — actual IDE context, the same signals a developer reads while working.

Install the companion extension, start the bridge, open Claude. That's it. Claude can now navigate your codebase the way you do, run tests, check diagnostics, commit, and create PRs — without you copy-pasting anything.

Claude Code ──── bridge ──── VS Code extension ──── your editor state

Works from your phone. SSH into your dev machine, send a message, watch Claude fix bugs and run tests on your home machine while you're away.

Prerequisites: Claude Code CLI, Node.js ≥ 20

npm install -g claude-ide-bridge
cd /your/project
claude-ide-bridge init

init does four things:

1. Installs the companion VS Code/Windsurf/Cursor extension
2. Appends a ## Claude IDE Bridge section to your CLAUDE.md (creating it if needed)
3. Writes .claude/rules/bridge-tools.md — a rules file that directs Claude to call MCP tools instead of shell equivalents (runTests instead of npm test, getDiagnostics instead of tsc, gitCommit instead of git commit, searchWorkspace instead of grep)
4. Registers the bridge as a global MCP server in ~/.claude.json so bridge tools appear in every claude session, any directory

The rules file is loaded automatically via @import in CLAUDE.md on every session. No extra flags or configuration needed.

Then start the bridge and open Claude:

claude-ide-bridge --watch   # terminal 1 — keeps running, auto-restarts on crash
claude --ide                # terminal 2 — Claude Code with IDE tools active

--watch restarts the bridge automatically if it crashes, with exponential backoff (2s → 30s). Safe for long-running sessions.

Type /mcp in Claude to confirm the server is connected, then /ide to see open files, diagnostics, and editor state.

One bridge per workspace. Each project needs its own bridge instance on its own port. If you work across multiple repos, start a separate claude-ide-bridge --watch in each directory.

Why ~/.claude.json and not .mcp.json? When VS Code, Windsurf, or Cursor launches Claude Code, it injects --mcp-config which overrides any project .mcp.json. Only ~/.claude.json is loaded in every session regardless of how Claude Code is started. init writes there by design — you don't need to touch .mcp.json.

Adding the bridge to an existing project (without re-running full init):

claude-ide-bridge gen-claude-md --write

This appends the bridge section to your existing CLAUDE.md and writes .claude/rules/bridge-tools.md. Run it once per project.

Tools not showing up? See the troubleshooting guide.

By default, the bridge starts in slim mode — 48 IDE-exclusive tools that Claude can't replicate with its built-in Read/Write/Bash tools: LSP intelligence, debugger, editor decorations, diagnostics, refactoring, impact analysis, and editor state. This is the right default for most workflows because Claude already has file editing and shell access built in.

If you need Claude to use the bridge's git, terminal, file ops, HTTP client, or GitHub tools instead of its built-in equivalents, start in full mode:

claude-ide-bridge --watch --full   # all ~130 tools

Or set it permanently in your config file (claude-ide-bridge.config.json):

{
  "fullMode": true
}

When to use --full:

• You're running headless/CI and want structured git/GitHub tools instead of raw git commands
• You want Claude to use runTests (with framework detection and structured output) instead of npm test
• You need sendHttpRequest with SSRF protection, or githubCreatePR with template support
• You're using automation hooks (--automation) that need terminal or git tools

When slim mode is enough (most users):

• You're working in VS Code/Cursor/Windsurf and want Claude to see your IDE state
• Claude's built-in Read/Write/Bash tools handle file ops and git fine
• You want a smaller tool list for faster responses and less token overhead

See MCP Tools below for the full tool breakdown by category.

With the bridge connected, try these prompts in Claude:

• "Explain the function at src/server.ts:140" — uses explainSymbol to get type info, docs, callers, and references in one call
• "Preview what renaming handleRequest to processRequest would change" — uses refactorPreview to show affected files without applying
• "Review this file and highlight issues inline" — Claude uses setEditorDecorations to annotate your editor with findings
• "Fix all errors in open files" — uses getDiagnostics to find errors, then editText to fix them
• "Show me who calls this function" — uses getCallHierarchy to trace callers and callees
• "Run the tests and fix failures" — uses runTests or runCommand to execute tests, reads output, and applies fixes
• "Create a PR for these changes" — uses getGitDiff, gitCommit, and githubCreatePR to commit and open a pull request

When to use this: Large projects (50k+ lines) where a single Claude session runs out of context mid-task, or where you're running genuinely parallel workstreams — one agent implementing while another reviews, or one exploring the backend while another works on the frontend. For most projects, a single bridge is sufficient.

Run two bridges simultaneously — one per IDE window — with a meta-orchestrator routing between them. Each agent gets a completely independent context (separate LSP cache, open files, terminal history), so their work doesn't interfere.

Claude Code
    │
Meta-Orchestrator (port 4746)
    ├── Bridge A (port 55000) — e.g. backend work, active changes
    └── Bridge B (port 55001) — e.g. frontend work, or clean reviewer

Setup (each IDE needs a fixed port):

In each VS Code/Windsurf workspace settings, set claudeIdeBridge.port to 55000 and 55001 respectively. Then:

claude-ide-bridge orchestrator --port 4746
claude --ide   # auto-discovers orchestrator, exposes both workspaces' tools

Use switchWorkspace ws1 / switchWorkspace ws2 in Claude to pin to a specific IDE. Tools from both are available; conflicting names get a __<IDE>_<port> suffix.

Concrete use cases where it pays off:

• Large monorepo: database layer in one IDE, API layer in another — each agent stays focused without context bleed
• Implement + review: one agent writes, the other reviews the diff with fresh eyes (no anchoring bias)
• Self-hosting dev loop: modify the bridge itself in IDE A, validate through IDE B without downtime

Where it's not worth the overhead: projects under ~50k lines, tasks that need to touch both workspaces frequently (handoff cost dominates), or anything a single runClaudeTask subprocess handles adequately.

See docs/multi-ide-review.md for the staged review workflow.

These guides are essential for setup and deployment — not optional reading. Each covers a specific scenario you'll encounter when running the bridge beyond localhost.

Reference docs (in documents/):

The bridge persists state across restarts and context switches (CLI ↔ Desktop ↔ Cowork).

Use setHandoffNote to save context before switching sessions. Notes are workspace-scoped — switching workspaces won't overwrite each other's context. getHandoffNote retrieves the most recent note for your current workspace.

The bridge also auto-snapshots a basic handoff note whenever a new session connects and the existing note is stale (>5 minutes old).

When the bridge restarts within 5 minutes of the previous run, it automatically restores the list of open files from the last session checkpoint. The first connecting client receives a notification:

Session restored from checkpoint: N file(s) tracked (checkpoint was Xs old)

1. CLI session: work normally; bridge tracks opened files
2. Switching to Desktop: call setHandoffNote first, or run /mcp__bridge__cowork to auto-collect context
3. Cowork: MCP tools are NOT available inside Cowork — the handoff note is the bridge. Always run /mcp__bridge__cowork in regular chat before opening Cowork (Cmd+2).

Cowork sessions (Claude Desktop computer-use): MCP bridge tools are NOT available inside Cowork. Run /mcp__bridge__cowork in a regular Desktop chat first to capture context, then open Cowork. Cowork also operates in an isolated git worktree — files won't appear in your main git status until merged.

The start-all command launches everything in a tmux session: bridge + Claude Code + remote control, with automatic health monitoring and process restart.

# Via npm global install or npx
claude-ide-bridge start-all --workspace /path/to/your-project

# Or the dedicated alias
claude-ide-bridge-start --workspace /path/to/your-project

# From source
npm run start-all -- --workspace /path/to/your-project

Options:

Requires tmux and the claude CLI to be on PATH.

The bridge ships as a Claude Code plugin with 9 skills, 3 subagents, and 16 hook events — available on the Claude Code plugin directory:

# Load the plugin
claude --plugin-dir ./claude-ide-bridge-plugin

Remote sessions (claude remote-control): Skills marked "CLI fallback" work without the bridge by using built-in Claude Code tools. Skills marked "Requires bridge" need the claude --ide session.

The bridge exposes tools in two modes:

• Slim mode (default) — 48 IDE-exclusive tools. Only tools that require a live VS Code extension and have no native Claude equivalent. This is what you get with claude-ide-bridge --watch.
• Full mode (--full) — all ~130 tools, adding git, terminal, file ops, HTTP, and GitHub. Use this for large projects or workflows that rely on those integrations.

The bridge exposes 15 built-in slash commands via the MCP prompts/list + prompts/get protocol. These appear as /mcp__bridge__<name> in any MCP client that supports prompts.

Cowork sessions and MCP tools: MCP tools (including all bridge tools) are not available inside a Cowork session. Use a two-step workflow: run /mcp__bridge__cowork in a regular Claude Code chat first — it gathers full IDE context and produces an action plan — then open a Cowork session armed with that context.

Prompts are served directly from the bridge — no extension required. Implemented in src/prompts.ts.

The bridge exposes your workspace files as MCP Resources via resources/list and resources/read. Any MCP client that supports the resources protocol can browse and read files directly — without calling individual file tools.

• Workspace tree is walked automatically (skips node_modules, .git, dist, etc.)
• Only text file extensions are exposed
• Cursor-paginated (50 files per page)
• 1 MB per-file cap
• Workspace-confined: paths outside the workspace are rejected

No configuration needed — resources are enabled by default.

The bridge exposes several HTTP endpoints for monitoring and integration. All require Authorization: Bearer <token> except /.well-known/mcp.

TOKEN=$(cat ~/.claude/ide/*.lock | python3 -c "import sys,json; print(json.load(sys.stdin)['authToken'])")

# Live tool call feed
curl -N -H "Authorization: Bearer $TOKEN" http://localhost:PORT/stream

# Prometheus scrape
curl -H "Authorization: Bearer $TOKEN" http://localhost:PORT/metrics

The bridge instruments every tool call with OpenTelemetry spans. Tracing is zero-overhead when disabled (the default).

# Export traces to any OTLP-compatible collector (Jaeger, Datadog, Honeycomb, etc.)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 claude-ide-bridge
OTEL_SERVICE_NAME=my-bridge claude-ide-bridge  # optional service name override

Spans are exported on process exit. No bridge code changes needed — the env var activates tracing automatically.

The bridge can spawn Claude subprocesses, queue tasks, and drive event-driven automation directly from VS Code events.

# Enable subprocess driver + event-driven automation with a policy file
claude-ide-bridge --workspace /path/to/project \
  --claude-driver subprocess \
  --automation \
  --automation-policy ./automation-policy.json

{
  "onDiagnosticsError": {
    "enabled": true,
    "minSeverity": "error",
    "prompt": "Fix the errors in {{file}}:\n{{diagnostics}}",
    "cooldownMs": 30000
  },
  "onFileSave": {
    "enabled": true,
    "patterns": ["**/*.ts", "!node_modules/**"],
    "prompt": "Review the saved file: {{file}}",
    "cooldownMs": 10000
  },
  "onFileChanged": {
    "enabled": true,
    "patterns": ["**/*.ts"],
    "prompt": "A file was edited: {{file}}. Run getDiagnostics to check for new errors.",
    "cooldownMs": 15000
  },
  "onCwdChanged": {
    "enabled": true,
    "prompt": "Working directory changed to {{cwd}}. Call getBridgeStatus and getOpenEditors to orient.",
    "cooldownMs": 10000
  },
  "onPostCompact": {
    "enabled": true,
    "prompt": "Context was compacted. Call getOpenEditors and getDiagnostics to rebuild your understanding of the current state.",
    "cooldownMs": 60000
  },
  "onInstructionsLoaded": {
    "enabled": true,
    "prompt": "Call getToolCapabilities to confirm the bridge is connected and note which tools are available for this session."
  },
  "onTestRun": {
    "enabled": true,
    "onFailureOnly": true,
    "prompt": "Tests failed ({{failed}}/{{total}}). Fix the failures:\n{{failures}}",
    "cooldownMs": 15000
  }
}

When automation is active, VS Code save/change events, diagnostic errors, and Claude Code hook events automatically enqueue Claude tasks. Output streams to the "Claude IDE Bridge" output channel in real time.

Policy triggers:

Cloud sessions: If CLAUDE_CODE_REMOTE=true (Claude Code on the web), automation tasks will still enqueue but the bridge itself runs locally — those tasks will not execute. Guard policy prompts or the onInstructionsLoaded hook with an environment check if needed.

A GET /tasks HTTP endpoint (Bearer-auth required) provides a sanitized task list for external monitoring.

Use with claude -p for automation:

# Fix all lint errors
claude -p "Use getDiagnostics to find all errors, then fix them" \
  --mcp-config ./mcp-bridge.json

# Run tests and fix failures
claude -p "Run tests with runTests, fix any failures, and commit" \
  --mcp-config ./mcp-bridge.json

# Generate architecture overview
claude -p "Map the project using getFileTree, getDocumentSymbols, and getCallHierarchy" \
  --mcp-config ./mcp-bridge.json --output-format json

When the bridge restarts, it picks up where it left off — restoring the set of files you had open in Claude's view of the workspace.

What's restored:

• Open file tracking (the set of files Claude was aware of across the last session's activity)
• Task queue — pending and running tasks survive bridge crashes and restarts (persisted to ~/.claude/ide/tasks-<port>.json)
• Activity log — all tool calls from past sessions remain readable

What isn't restored:

• In-progress tool calls (those are cancelled on disconnect)
• Live diagnostics (always fetched fresh from the extension)
• Claude's own conversation context (that's Claude Code's responsibility, not the bridge's)

How it works: The bridge checkpoints session state every 30 seconds to ~/.claude/ide/. On startup, the first connecting Claude session is seeded with the union of all previously-tracked open files. No configuration needed — this is on by default.

Beta caveat: Checkpoint restore is file-list only. Full "resume from mid-task" support (restoring partial tool progress, re-streaming output) is not yet implemented.

Run the bridge on a remote server with no display — give Claude full IDE capabilities over SSH without opening a desktop environment.

Recommended: VS Code Remote-SSH or Cursor SSH

Connect your local VS Code, Cursor, or Windsurf to a VPS via Remote-SSH. The bridge extension runs in the remote extension host automatically — no extra setup. LSP, debugger, terminals, and all editor-state tools work normally because the extension and bridge run together on the server.

Windsurf SSH tip: Windsurf with an active SSH session counts as Remote-SSH — the extension loads on the VPS side and connects to the bridge. Confirm with curl .../health and look for "extension": true.

Fully headless (no IDE)

For servers with no VS Code at all:

# On the VPS — install Node.js 20 + the bridge
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs
npm install -g claude-ide-bridge

# Generate a stable token (survives restarts — save this value)
export BRIDGE_TOKEN=$(uuidgen | tr '[:upper:]' '[:lower:]')

# Start the bridge in the background with tmux
tmux new-session -d -s bridge 'claude-ide-bridge --bind 0.0.0.0 --port 9000 --fixed-token $BRIDGE_TOKEN --workspace /path/to/project'

# Confirm the token
claude-ide-bridge print-token --port 9000

# On your local machine — write an MCP config pointing at the VPS
# Run from inside your project directory (merges into the nearest .mcp.json)
bash scripts/gen-mcp-config.sh remote \
  --host your-vps-ip:9000 \
  --token <token-from-above> \
  --write

Available tools in headless mode: file operations, git, terminals, search, CLI linters, dependency audits, HTTP client. LSP, debugger, and editor-state tools require the extension.

Stable tokens: Use --fixed-token <uuid> (or CLAUDE_IDE_BRIDGE_TOKEN=<uuid>) to keep the same token across restarts. Without it, a new token is generated each time the bridge starts, requiring a config update.

VPS filesystem scope: A bridge running on a VPS serves that VPS's filesystem only. File tools (readFile, writeFile, searchWorkspace, etc.) read and write files on the VPS — not on your local Mac. If you want Claude to work on files on your local machine, run the bridge locally (or use VS Code Remote-SSH, which runs both the extension and bridge on the VPS alongside your remote files).

Security: --bind 0.0.0.0 exposes the bridge to the network. Put nginx or Caddy in front with TLS before exposing to the internet. See docs/remote-access.md for a production Caddy setup.

Install the extension in any supported editor:

# Auto-detect editor
claude-ide-bridge install-extension

# Specify editor
claude-ide-bridge install-extension windsurf
claude-ide-bridge install-extension cursor

# Or via the install script
bash scripts/install-extension.sh --ide <name>

Run the bridge on a VPS with the IDE on your local machine — full tools, no compromise.

When you connect VS Code or Cursor to a VPS via SSH, the extension host runs on the VPS. The bridge extension runs there too — it spawns the bridge, polls lock files, and connects over VPS localhost. Nothing needs to change on your end.

Setup:

1. Install the extension in VS Code/Cursor locally (it will auto-install on the VPS via SSH)
2. Connect via Remote-SSH and open your VPS workspace
3. The extension activates on the VPS, auto-installs claude-ide-bridge if needed, and starts the bridge
4. Claude Code on your local machine connects normally via the lock file

All tools are available — LSP, debugger, terminals, git, diagnostics — because the extension runs alongside the bridge on the same machine.

For VPS environments without VS Code (e.g. a pure server setup):

# On the VPS — start bridge with a stable token so it survives restarts
export BRIDGE_TOKEN=$(uuidgen | tr '[:upper:]' '[:lower:]')
tmux new-session -d -s bridge 'claude-ide-bridge --bind 0.0.0.0 --port 9000 --fixed-token $BRIDGE_TOKEN --workspace /path/to/project'

# Get the auth token
claude-ide-bridge print-token --port 9000

# On your local machine — generate and write the MCP config
# Run from inside your project directory (merges into the nearest .mcp.json)
bash scripts/gen-mcp-config.sh remote \
  --host your-vps-ip:9000 \
  --token <token-from-above> \
  --write

Stable tokens: --fixed-token keeps the same token across bridge restarts so your local config stays valid. Without it, the token changes every restart.

Security: --bind 0.0.0.0 exposes the bridge to your network. For production, put nginx or Caddy in front with TLS. The remote config generator uses http:// — update the URL to https:// once TLS is in place.

Available tools in headless mode: file operations, git, terminals, search, CLI linters, dependency audits, HTTP client. LSP, debugger, and editor-state tools are unavailable without the extension.

Connect the Claude Desktop app to your running bridge — chat with your IDE using natural language.

# Generate the config (prints to stdout)
bash scripts/gen-claude-desktop-config.sh

# Write it to the config file (backs up existing config)
bash scripts/gen-claude-desktop-config.sh --write

Then restart Claude Desktop once to load the new config. After that, the bridge's stdio shim handles everything automatically — it discovers the running bridge via lock files, buffers requests until connected, and reconnects transparently when the bridge restarts. No port or token needs to be hard-coded, and no further Desktop restarts are needed when the bridge restarts.

Tool availability: Without the VS Code extension connected, ~48 tools (debugger, LSP intelligence, editor state, decorations, refactoring) are unavailable. Claude Desktop works best alongside the running extension. You can verify connectivity by asking "What tools do you have available?" — the response will list what's active.

Debugging the shim: If the connection seems stuck, the shim logs to stderr. In Claude Desktop, check Settings → Developer → MCP Logs to see shim output. Common cause: bridge not running — start it with claude-ide-bridge --watch first.

Try it: Open Claude Desktop and ask "What diagnostics are in my workspace?" or "What files are open in my IDE?"

You can also use the general config generator:

bash scripts/gen-mcp-config.sh claude-desktop --write

Config location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Dispatch is a Claude Desktop feature that lets you send instructions from your phone to your desktop Claude session. Combined with the bridge, you can check on your project, run tests, and review changes — all from a phone message.

Your Phone (Claude App)
    │
    ▼  terse instruction
Claude Desktop (main conversation)
    │
    ▼  MCP tool calls
Bridge Server ──► IDE Extension ──► Your Code
    │
    ▼  results
Claude Desktop
    │
    ▼  concise summary
Your Phone

Dispatch messages land in Claude Desktop's main conversation, which has full MCP bridge access. Claude calls the bridge tools, gathers results, and sends a summary back to your phone.

Not Cowork: Dispatch routes through the main conversation, not a Cowork session. All 130+ bridge tools are available. The Cowork tool-access limitation does not apply here.