Claude IDE Bridge

MCP bridge giving Claude Code IDE superpowers: 141 tools for LSP, debugging, git, GitHub, terminals, and more.

A WebSocket bridge between Claude Code CLI and your VS Code extension. Claude sees what your IDE sees — live diagnostics, go-to-definition, call hierarchies, hover types, breakpoints, debugger state — and can act on it: edit files, run tests, commit, open PRs, all without you copy-pasting anything.

Works locally, over SSH, in Docker, and on a VPS. Extension is optional — headless mode covers git, terminals, GitHub, and LSP via typescript-language-server.

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

See it work in 5 minutes: save a broken file, Claude notices, diagnoses, proposes a fix — no prompt typed. Self-healing quickstart →

https://github.com/user-attachments/assets/a81a8d11-2cc3-46f3-88ad-6a905a221a2c

Quick Start

Prerequisites: Claude Code CLI, Node.js ≥ 20

# 1. Install the bridge
npm install -g claude-ide-bridge

# 2. One-command setup (installs extension, writes CLAUDE.md, registers MCP server)
cd /your/project
claude-ide-bridge init

# 3. Start the bridge (full tool set is the default — add --slim for IDE-only)
claude-ide-bridge --watch

# 4. Open Claude Code — bridge connects automatically
claude --ide

Updating? Use npm install -g claude-ide-bridge@latest — npm update -g may lag the registry cache after a new release.

After init, type /mcp in Claude Code to confirm the bridge is connected. Type /ide to see open files, diagnostics, and editor state.

One bridge per workspace. Each project runs its own bridge instance on its own port. Start a separate claude-ide-bridge --watch in each directory.

Non-VS Code / headless users

npx claude-ide-bridge@latest init --headless
claude-ide-bridge --watch --full

Skips extension install, recommends full mode. LSP falls back to typescript-language-server if installed globally. See docs/headless-quickstart.md.

Installing the VS Code extension separately

claude-ide-bridge install-extension

Or search Claude IDE Bridge in the VS Code / Cursor / Windsurf marketplace.

Tool Categories

Discovering tools at runtime: ask Claude "call getToolCapabilities" in any connected session, type /mcp in Claude Code for live server state, or run claude-ide-bridge list-tools from the shell for a quick category summary. Full reference: documents/platform-docs.md. Auto-generated tool table: docs/tool-reference.md.

S = slim (opt-in via --slim) · F = full mode (default)

Slim vs Full Mode

The bridge starts in full mode by default (changed in v2.43.0) — all ~140 tools, covering LSP/debugger/refactoring plus git, GitHub, terminal, file tree, and orchestration.

Pass --slim to restrict to the ~60 IDE-exclusive tools (LSP, debugger, editor state only) — useful when you want Claude to use its native Read/Write/Bash tools for everything else:

claude-ide-bridge --slim --watch

Or set permanently in claude-ide-bridge.config.json:

{ "fullMode": false }

Use --slim when: - You prefer Claude's native Read/Write/Bash over bridge file/git/HTTP tools - Running in a locked-down environment and want to minimize exposed surface - You only need LSP navigation, debugger, and editor state signal

The --full flag is retained as a no-op opt-in for backward compatibility.

Usage Examples

Find every caller of a function

"Show me everything that calls processPayment()"

Claude runs getCallHierarchy — returns the full incoming call tree with file paths and line numbers, no grep required.

Fix all type errors in the workspace

"Fix the TypeScript errors in src/api/"

Claude calls getDiagnostics to get live compiler errors, then editText to patch each one. No build step needed — diagnostics are live from the language server.

Create a PR from the current branch

"Push my branch and open a PR against main"

Claude calls gitPush, then githubCreatePR — picks up your repo's PR template automatically and pre-fills it from recent commits.

Set a breakpoint and inspect a variable

"Break on line 42 of auth.ts and tell me what token contains"

Claude calls setDebugBreakpoints, startDebugging, then evaluateInDebugger — real debugger evaluation, not console.log guessing.

Refactor a symbol safely

"Rename UserService to AuthService everywhere"

Claude calls refactorAnalyze (checks blast radius and risk), refactorPreview (shows every edit before touching a file), then renameSymbol — language-server rename, not find-and-replace.

Deployment Options

Local (VS Code / Cursor / Windsurf)

Standard setup. Extension connects automatically. Full LSP, debugger, and editor state available.

Remote SSH

VS Code Remote-SSH and Cursor SSH load the extension on the VPS side (extensionKind: ["workspace"]). Start the bridge on the remote machine. All ~140 tools work over SSH.

# On the remote machine
claude-ide-bridge --watch --bind 0.0.0.0

VPS + systemd

Persistent bridge with automatic restarts, fixed auth token, and optional OAuth 2.0 for remote MCP clients (claude.ai, Codex CLI).

# Full provisioning
bash deploy/bootstrap-new-vps.sh

# Or just the service
bash deploy/install-vps-service.sh

See deploy/README.md and docs/remote-access.md.

Docker

docker run -p 3284:3284 ghcr.io/oolab-labs/claude-ide-bridge:latest --bind 0.0.0.0

Or with Compose:

docker compose up

Headless image includes typescript-language-server and universal-ctags for LSP and symbol search without VS Code. See documents/headless-quickstart.md.

Launch tasks from a terminal (headless parity)

The sidebar's quick-task buttons also work from the CLI — same context-gathering, same prompt-building, same dispatch path:

# 7 presets: fixErrors · refactorFile · addTests · explainCode · optimizePerf · runTests · resumeLastCancelled
claude-ide-bridge quick-task fix-errors
claude-ide-bridge quick-task add-tests --json

# free-form description (Claude gathers its own context)
claude-ide-bridge start-task "Refactor the auth module for clarity, keep behaviour identical"

# resume prior session from handoff note
claude-ide-bridge continue-handoff

Requires --claude-driver subprocess on the running bridge. All three subcommands accept --json, --port, --source. Enforces a 5s bridge-global cooldown per preset (shared with the sidebar).

Automation Hooks

Event-driven hooks that trigger Claude tasks automatically — no polling, no manual invocation.

{
  "hooks": [
    {
      "event": "onDiagnosticsError",
      "prompt": "Fix the type error in {{file}}: {{diagnostics}}",
      "cooldownMs": 30000
    },
    {
      "event": "onFileSave",
      "patterns": ["src/**/*.ts"],
      "prompt": "Run tests for {{file}} and fix any failures"
    },
    {
      "event": "onGitCommit",
      "prompt": "Review commit {{hash}}: {{message}}"
    }
  ]
}

Start with:

claude-ide-bridge --watch --automation --automation-policy ./policy.json --claude-driver subprocess

18 hook events: onFileSave, onFileChanged, onDiagnosticsError, onDiagnosticsCleared, onGitCommit, onGitPush, onGitPull, onBranchCheckout, onPullRequest, onTestRun, onTestPassAfterFailure, onPostCompact, onInstructionsLoaded, onTaskCreated, onTaskSuccess, onPermissionDenied, onCwdChanged, onDebugSessionEnd

All hooks support cooldownMs (min 5s), promptName/promptArgs for named prompts, and when conditions (minDiagnosticCount, testRunnerLastStatus). See docs/automation.md.

Plugin System

Extend the bridge with custom MCP tools without forking. Plugins load in-process alongside built-in tools and support hot reload.

# Scaffold a new plugin
claude-ide-bridge gen-plugin-stub ./my-plugin --name "org/my-plugin" --prefix "myPrefix"

# Load it
claude-ide-bridge --watch --plugin ./my-plugin --plugin-watch

Publish to npm with keyword claude-ide-bridge-plugin — users install by package name:

claude-ide-bridge --plugin claude-ide-bridge-my-plugin

See documents/plugin-authoring.md for the full manifest schema and entrypoint API.

Companion Marketplace

Install curated companion MCP servers directly into your Claude Desktop config:

claude-ide-bridge marketplace list
claude-ide-bridge marketplace search memory
claude-ide-bridge install claude-mem

install merges the companion into mcpServers in your Claude Desktop config atomically and idempotently — no manual JSON editing.

CLI Reference

Key flags:

Documentation