# 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](https://modelcontextprotocol.io), 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:

```sh
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](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

```text
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

```sh
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](FINDINGS.md)** — what the documentation does not say, measured or read out of the VS Code source
- **[bench/README.md](bench/README.md)** — the measurements, including the ones that went against the project
- **[reference/](reference/)** — VS Code's own source, pinned at 1.132.0, behind every API claim here

MIT.