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.

| Category | Count | Example tools | Mode | |---|---|---|---| | LSP & Code Intelligence | 29 | goToDefinition, findReferences, getCallHierarchy, getHover, explainSymbol | S | | Debugging | 6 | setDebugBreakpoints, startDebugging, evaluateInDebugger, getDebugState | S | | Refactoring | 5 | refactorAnalyze, refactorPreview, renameSymbol, refactorExtractFunction | S | | Editor State | 8 | getDiagnostics, getDocumentSymbols, getOpenEditors, contextBundle, watchDiagnostics | S | | Git | 12 | gitAdd, gitCommit, gitPush, getGitStatus, getGitDiff, gitCheckout, gitBlame | F | | GitHub | 5 | githubCreatePR, getPRTemplate, getGitHotspots | F | | Files & Search | 10 | findFiles, getFileTree, searchWorkspace, searchAndReplace, createFile, editText | F | | Terminal & Shell | 6 | runInTerminal, getTerminalOutput, runCommand, runVSCodeTask, listVSCodeTasks | F | | Claude Orchestration | 5 | runClaudeTask, listClaudeTasks, getClaudeTaskStatus, cancelClaudeTask | F | | Quality & Analysis | 11 | getCodeCoverage, auditDependencies, detectUnusedCode, generateTests, getSecurityAdvisories | F |

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

| Command | What it does | |---|---| | claude-ide-bridge init | One-command setup: install extension + write CLAUDE.md + register MCP server | | claude-ide-bridge --watch | Start bridge with auto-restart on crash (2s → 30s backoff) | | claude-ide-bridge --slim | Restrict to ~60 IDE-exclusive tools (default: ~140 full tools) | | claude-ide-bridge install-extension | Install companion VS Code extension | | claude-ide-bridge gen-claude-md --write | Add bridge section to existing CLAUDE.md | | claude-ide-bridge print-token | Print auth token from active lock file | | claude-ide-bridge gen-plugin-stub <dir> | Scaffold a new plugin | | claude-ide-bridge marketplace list | List available companion servers | | claude-ide-bridge install <companion> | Install companion into Claude Desktop config | | claude-ide-bridge notify <Event> | Post a hook event to a running bridge (for CC hook wiring) | | claude-ide-bridge quick-task <preset> | Launch a context-aware Claude task from a preset (headless parity with the sidebar) | | claude-ide-bridge start-task "<description>" | Enqueue a free-form Claude task with workspace context | | claude-ide-bridge continue-handoff | Resume prior session using the stored handoff note | | claude-ide-bridge start-all | Launch tmux session with bridge + extension watcher |

Key flags:

| Flag | Default | Description | |---|---|---| | --slim | off | Restrict to IDE-exclusive tools (default: full, ~140 tools) | | --full | on | No-op (retained for backward compat — full is the default since v2.43.0) | | --watch | off | Auto-restart on crash | | --bind <host> | 127.0.0.1 | Bind address (0.0.0.0 for remote access) | | --port <n> | auto | Port (auto-detected from lock files) | | --fixed-token <uuid> | — | Stable auth token across restarts | | --automation | off | Enable automation hooks | | --automation-policy <path> | — | Path to policy JSON | | --claude-driver subprocess | none | Enable Claude subprocess orchestration | | --plugin <path> | — | Load a plugin (repeatable) | | --plugin-watch | off | Hot-reload plugins on change | | --issuer-url <url> | — | Activate OAuth 2.0 mode | | --cors-origin <origin> | — | Add CORS origin (repeatable) | | --vps | off | Expand command allowlist for VPS use | | --grace-period <ms> | 120000 | Session preservation window across disconnects |

Documentation

| File | Description | |---|---| | ARCHITECTURE.md | System topology, request lifecycle, component map, design decisions | | documents/platform-docs.md | Full tool reference — all 141 tools with parameters and examples | | documents/prompts-reference.md | All MCP prompts (31 prompts, 12 plugin skills, 4 subagents) | | docs/automation.md | Automation hooks reference — all 18 events, policy schema, condition filters | | docs/troubleshooting.md | Diagnostics, common errors, and fixes | | docs/remote-access.md | VPS setup, OAuth 2.0, nginx/Caddy reverse proxy | | documents/headless-quickstart.md | CI, Docker, server use without VS Code | | docs/cowork.md | Computer-use (Cowork) workflow and git worktree setup — MCP bridge tools unavailable inside Cowork | | docs/multi-ide.md | Multiple sessions and parallel editor instances | | docs/migration.md | Upgrade guide between major versions | | documents/plugin-authoring.md | Plugin manifest schema, entrypoint API, distribution | | documents/styleguide.md | Code conventions, tool factory pattern, output formats | | docs/adr/ | Architecture Decision Records | | CONTRIBUTING.md | Contributor guide, build setup, test requirements | | deploy/README.md | VPS provisioning and systemd service scripts |

Requirements

• Node.js ≥ 20 (bridge)
• VS Code, Cursor, or Windsurf — optional. Headless mode covers git, terminals, GitHub, and LSP via typescript-language-server. Extension required for debugger, editor decorations, and live editor state.
• Claude Code CLI — for local use. Remote MCP clients (claude.ai, Codex CLI) work via Streamable HTTP transport with OAuth 2.0.

License

MIT — see LICENSE.

Contributing

Bug reports and PRs welcome. See CONTRIBUTING.md.

When reporting a bug, include the output of:

claude-ide-bridge print-token   # confirms bridge is running
# then in Claude: call getBridgeStatus

Per the project's bug fix protocol: a reproducing test must exist before a fix lands.

Powered-by badge

Using Claude IDE Bridge in a plugin, companion tool, or blog post? Drop in the badge:

[![Powered by Claude IDE Bridge](https://img.shields.io/badge/Powered%20by-Claude%20IDE%20Bridge-5A6FE0?logo=visualstudiocode&logoColor=white)](https://github.com/Oolab-labs/claude-ide-bridge)

<a href="https://github.com/Oolab-labs/claude-ide-bridge"><img src="https://img.shields.io/badge/Powered%20by-Claude%20IDE%20Bridge-5A6FE0?logo=visualstudiocode&logoColor=white" alt="Powered by Claude IDE Bridge"></a>