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:

When	What happens
Session start	it learns which workspace is open, what you are looking at, which files are unsaved
After a file read	a warning if what it just read from disk is stale in your editor
Before a write	the write is blocked if you have unsaved changes in that file
After a write	the errors the language services now report for it

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

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

Editor state	get_workspace get_active_editor
Reading	read_range — the live buffer, with the version an edit needs
Search	search_workspace — honours the editor's own exclude settings
Navigation	find_definition find_references find_implementations find_workspace_symbols get_document_symbols get_call_hierarchy
Understanding	describe_symbol — signature and docblock, without opening the file
Diagnostics	get_diagnostics
Fixes	get_code_actions apply_code_action — pick the fix the editor already computed
Editing	apply_edit rename_symbol revert_last_edit
Terminal	get_terminal_history — what you ran, and what came back
Environment	get_language_support — which languages answer, and which formatter is really running

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.

Area	What is checked
Reading	ranges return only the requested lines; the document version comes back for edit safety
Search	hits as path:line:col │ text; include globs respected
Security	.env refused by reads and absent from search results; ../ escapes refused; no token → 401; foreign Origin → 403; loopback-only bind
Navigation	definition across files, references, implementations, call hierarchy, symbol by name
Diagnostics	a seeded type error is reported, including in a file that was never opened
Failure modes	unknown symbol → not_found, never an empty list; bad range → invalid_range
Editing	stale version and stale text are both refused instead of overwriting
Refactoring	rename across 3 files, no stale references, no new diagnostics
Incompleteness	references and renames report call sites reached through a dynamic import, which the language service cannot see
Undo	one revert_last_edit restores a 3-file rename; reverting twice refuses
Cold index	the first symbol search on a freshly opened workspace returns results, not an empty list
Distribution	the VSIX installs and activates; the plugin shim connects and lists every tool

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.