VS Code Agent Bridge

Your editor knows things about your code that your AI agent cannot see. This connects them.

An agent working in your repository reads files from disk and searches text. That is all it has. Meanwhile the editor sitting next to it has already resolved which symbol is which, knows where your cursor is, and holds the changes you have not saved yet — and none of that reaches the agent.

Three situations where the gap costs you:

Five modules export a function called install. You ask for one of them to be renamed. Text search finds fourteen occurrences — some in comments, one inside a string, most belonging to the other four modules — and the agent has to guess which are real. The editor does not guess: it knows exactly which three are references.

You have unsaved changes on screen. You ask what a constant is set to right now. The agent reads the file from disk, finds the old value, and answers confidently. It is wrong, and nothing in its view says so. Measured: wrong three times out of three.

You say "refactor this". Nothing on the filesystem records what "this" is — which file you are looking at, what you have selected. No file tool can answer it.

What it does

A VS Code extension exposes the editor over MCP, so the agent can ask instead of infer:

• where a symbol is really used — not where the word appears

• a function's signature and docblock — without reading the file it lives in

• what you are looking at — file, cursor, selection, unsaved state

• the errors the editor reports now — every language server and linter at once, no compiler run

• rename through the language service — the F2 path: imports updated, one undo reverses it

And three things arrive without the agent asking, which is what actually changes outcomes:

A tool nobody remembers to call prevents nothing. The push is the point.

Related MCP server: VSC as MCP

Install

Two pieces, because one of them has to run inside the editor:

npm install && npm run package
code --install-extension vscode-agent-bridge.vsix   # the extension
claude --plugin-dir packages/plugin                 # the plugin

Then open VS Code on your project. The status bar shows ⇄ Bridge :51734 and you are done — no port to configure, no token to copy. The plugin finds the window whose workspace contains your session's directory, which is also how several open windows stay out of each other's way.

Any MCP-capable agent can use the server; Claude Code is the one with a plugin ready.

Uninstall with code --uninstall-extension mend3.vscode-agent-bridge.

Where it does not help

Measured, including the results that went against it — see bench/README.md:

• It does not replace Read, grep or the terminal. It does not try: there is no read_file and no filename search in it, because the native tools do those better.

• It is not faster or cheaper on simple tasks. On "find the usages of X", grep is already excellent; the bridge tied or cost about 14% more.

• With no VS Code window open it does not exist. The agent falls back to normal tools — degradation, not failure.

• It inherits your editor's setup. Without a Python extension, Python is opaque text. get_language_support answers exactly that: which languages are actually responding.

The gain is in what only the editor knows. On "rename the function my cursor is on", the agent without the bridge scored 0 of 3 — and, to its credit, refused rather than guessing. With the bridge, 3 of 3.

Tools

Read tools are annotated read-only; write tools ask before touching the workspace unless agentBridge.writeMode is auto. Every edit is a single WorkspaceEdit, so revert_last_edit puts back everything the last one touched — and refuses if the files moved on since.

How it connects

VS Code opens a workspace
  └─ extension activates, binds 127.0.0.1:<ephemeral>, generates a 32-byte token
     └─ writes ~/.vscode-agent-bridge/instances/<pid>.json   (dir 0700, file 0600)

Agent starts in that directory
  └─ plugin runs bin/bridge-stdio.mjs (stdio ⇄ HTTP proxy)
     └─ reads the registry, drops dead pids, picks the window whose workspace
        contains this session's directory, then proxies with the bearer token

The port is ephemeral and changes on every restart, so nothing static can point at it. The shim resolves the window at connect time — that is what makes the setup zero-configuration.

The server listens on loopback only, with a per-session bearer token and an Origin check, and refuses paths outside the workspace or matching the blocked-path list (.env, keys, secrets/**).

Develop

npm run build
code --extensionDevelopmentPath=$PWD/packages/extension fixtures/ts-sample
npm test          # drives a live bridge over MCP and asserts the results

node packages/plugin/bin/bridge-doctor.mjs [projectDir] answers "why isn't it connected?" — registry, live windows, resolution, health check.

Verified

19 tools, 28/28 end-to-end checks against the installed extension on a real VS Code window, because the behaviour worth testing only exists there.

Further

• FINDINGS.md — what the documentation does not say, measured or read out of the VS Code source

• bench/README.md — the measurements, including the ones that went against the project

• reference/ — VS Code's own source, pinned at 1.132.0, behind every API claim here

MIT.