Skip to main content
Glama
vscode

vscode

by pearnaly

vscode-control

Two MCP tools that let Claude Code act in the VS Code window it runs in:

  • open_file — open a file beside the Claude chat (or in a given editor group) at a line, optionally selecting a range; keyboard focus stays in the chat unless focus: true (e.g. for typing a secret).

  • reveal_in_explorer — show a file or folder in the Explorer side panel.

It consists of a VS Code extension (extension/) and a stdio MCP bridge (bridge/) that Claude Code starts. Both are built from this repository.

Requirements

  • VS Code 1.95 or newer. Local windows and Remote-SSH windows work; WSL and dev-container windows are untested. In a Remote-SSH window the extension and Claude Code both run on the remote host, so install the extension there; the bridge, the claude mcp add registration and Node.js live on the remote host too.

  • Node.js 22.12 or newer: it runs the bridge and builds the project.

  • Claude Code, with its VS Code extension. "Beside the chat" means beside that extension's chat tab; when the chat is not an editor tab, VS Code's own "beside" is used.

  • To follow the install steps below: npm, and the code and claude commands on your PATH.

Related MCP server: claude-cursor-mcp

Platform status

Developed and tested on Windows 11. Linux works: it was run through Remote-SSH, and the test suite passes there. macOS is untested and should work the same way as Linux. On Linux and macOS the bridge reads the process table with ps instead of PowerShell. It starts ps by absolute path (/bin/ps or /usr/bin/ps), from / as the working directory, and fails if neither exists. ps reports no creation times, so the creation-time check in the ancestor walk (see Security) does not apply there, and neither does the start-time check for stale discovery files (also see Security): both run on Windows only.

"Beside the chat" finds the chat through the Claude Code chat tab's internal view type, claudeVSCodePanel. That name is not a public interface and may change; if it does, open_file falls back to VS Code's own "beside".

How it works

Claude Code ──stdio MCP──▶ bridge (one per session) ──HTTP + bearer token──▶ extension (one per window) ──▶ VS Code API
  • The extension (extension/) starts in every VS Code window, listens on 127.0.0.1:<random port> with a random 32-byte token, and writes ~/.vscode-control/windows/<extension-host-pid>.json (on Windows %USERPROFILE%\.vscode-control\windows\) with the port, token, workspace folders, window name, last focus and the extension host's start time (startedAt, used by the stale-file check on Windows, see Security). The file is removed when the window closes.

  • The bridge (bridge/) is a stdio MCP server that Claude Code starts per session. It picks the window whose extension host is an ancestor of the bridge process (that is the window running the Claude session), else the window whose workspace contains the session folder, else the most recently focused window. Results end with [window chosen by folder match] or [window chosen by last focus] when a fallback was used. Claude in an external or the integrated terminal is always matched by that fallback: integrated-terminal shells hang off VS Code's shared pty host, not the extension host, so the label is expected there.

  • Register the bridge as a plain stdio server, not behind a shared MCP gateway: it identifies the window through its own process ancestry, so a bridge that is not a descendant of the Claude session can only use the folder and focus fallbacks.

  • In a Remote-SSH window the extension runs in the remote extension host (it declares "extensionKind": ["workspace"]), the same host where Claude Code starts its sessions, so the ancestry match works there too. The discovery files are then in the remote host's home directory.

Install / update

Build, package and install the extension from source. With Remote-SSH, do all of this on the remote host (see Requirements).

npm install
npm run build
npm test
npm run package             # → vscode-control.vsix
npm run install-extension   # code --install-extension vscode-control.vsix --force

Then register the bridge with Claude Code:

claude mcp add --scope user vscode -- "<absolute path to node>" "<repo>/bridge/dist/index.js"

On Windows, for example:

claude mcp add --scope user vscode -- "C:\Program Files\nodejs\node.exe" "C:\path\to\vscode-control\bridge\dist\index.js"

node has to be an absolute path because the session's working directory may be an untrusted repository, and a bare node could be resolved from there. After the first registration, running Claude sessions only see the tools after /mcp or in a new session.

After an extension update VS Code may ask to reload the window. Reloading restarts the extension host, which ends Claude sessions running in that window; resume them afterwards. After a bridge update, new Claude sessions pick it up; running sessions keep the old one until /mcp → reconnect.

Check it

npm run smoke                                         # list tools, open README.md 1–3, reveal README.md
node scripts/smoke.mjs open_file '{"path":"C:\\...\\file.ts","line":10,"endLine":20,"group":"beside"}'

(PowerShell 7.3+ or Git Bash; in Windows PowerShell 5.1 escape each inner double quote with a backslash, e.g. {\"path\":\"C:\\...\"})

Manual checklist (after install):

  1. Walkthrough: open_file with line/endLine → file opens beside the chat with the block selected; you can keep typing in the chat.

  2. Secret: create a file with a placeholder; open_file with focus: true and the placeholder selected → the cursor is in the file and typing replaces the placeholder.

  3. reveal_in_explorer → the Explorer shows and selects the item; focus returns to the chat.

  4. reveal_in_explorer with focus: true → focus stays in the Explorer.

  5. Two windows open → calls act in the window running the Claude session.

  6. Claude in an external or the integrated terminal → result says [window chosen by folder match] or [window chosen by last focus].

How Claude is told to use it

The server instructions sent with the MCP handshake and the two tool descriptions (bridge/src/descriptions.ts) encode a usage policy:

  • On request: when you ask to see code or to find something, Claude opens the file or reveals it in the Explorer.

  • Walkthroughs: for a guided tour of an implementation, Claude opens each relevant file in turn with the relevant block selected (line/endLine) and leaves focus in the chat.

  • Secret entry: Claude creates a file with a placeholder in a place that is neither committed nor synced (outside any cloud-synced folder, and gitignored or outside any repository), opens it with focus: true and the placeholder selected, waits until you say you are done, and never reopens that file with a selection.

  • On its own initiative: sparingly, at most the main file of a finished task.

Security

  • Local only. The extension's HTTP server listens on 127.0.0.1 on a random free port. It answers only POST /call, everything else gets 404, and request bodies over 64 KB are refused.

  • A token per window. Each activation of the extension generates a 32-byte random token. A request without the matching Authorization: Bearer header gets 401 before its body is read; the comparison is constant-time.

  • Discovery files stay in your user profile. ~/.vscode-control/windows/<pid>.json holds the port and token. On macOS and Linux the directory is created with mode 0700 and the files with 0600; on Windows the user-profile ACL protects them. The extension deletes its file when the window closes, and the bridge deletes the files of dead processes.

  • Two fixed operations. The server accepts only open_file and reveal_in_explorer, with strictly validated arguments. The extension executes no command line and starts no process; the only VS Code commands it invokes are revealInExplorer and workbench.action.focusActiveEditorGroup.

  • open_file accepts any absolute path, on purpose. The secret-entry flow needs files outside the workspace, and the only caller is your own Claude session, which can normally read those files anyway. The tool returns a one-line status (what was opened, where, in which window), never file content. reveal_in_explorer is limited to the window's workspace folders. Caveat: if you rely on Claude Code permission rules (for example a Read deny for ~/.ssh) to keep files away from Claude, open_file can still open such a file and select text in it, and Claude Code's VS Code integration shares the editor's selected text with Claude. So treat open_file as able to read any file the VS Code user can read, or do not register it in setups that depend on such rules.

  • Network paths only inside the workspace. Network (UNC) paths such as \\server\share\file are only opened or revealed inside the window's workspace folders. Anywhere else the call is refused before any file-system access, because Windows would connect to that host and send your credentials. VS Code's own security.allowedUNCHosts restriction applies as well.

  • PowerShell by absolute path. On Windows the bridge reads the process table with %SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe and starts it with its own directory as the working directory, so nothing planted in the session's folder, which may be an untrusted repository, is executed or loaded.

  • Ancestry needs name = pid. A discovery file counts only if its name is exactly <pid>.json for the pid it contains, so a file cannot claim a window's pid under another name. The ancestor walk also stops at a parent that is gone or was created after its child, because Windows can reuse the pid of a dead parent.

  • Stale discovery files. After a crash a window's file stays behind, and its pid may be reused. Files of dead pids are deleted whenever a bridge reads the folder. On Windows, which reuses pids much sooner than Linux, the extension also records when its process started (startedAt, since 0.2.0) and the bridge compares it with the creation time in the OS process table. A file whose pid now belongs to a process started after that window is deleted and never contacted (when the bridge could read the process table). A file whose process was not running when the session started is ignored for the session but not deleted, because that verdict rests on the window's own clock. Linux and macOS hand out pids sequentially, so reuse needs a wrap-around; there, and for files written by 0.1.x, a refused connection still makes the bridge forget the file and retry once with the next window. Not covered: a window that crashes after the bridge read the process table (once per session) and whose pid is reused within that session.

Troubleshooting

  • "No VS Code window with vscode-control is running": the extension is not installed or not activated in any window. Check the Extensions view, then the Output panel → "vscode-control" (first line: extension version, listening port and discovery file).

  • "Token rejected": reload that window.

  • "Could not reach" the session's own window: the extension there is not answering; reload that window (this also restarts the Claude sessions running in it).

  • Wrong window: look at the [window chosen by …] suffix; the discovery files in ~/.vscode-control/windows/ (on Windows %USERPROFILE%\.vscode-control\windows\) show what each window advertises.

  • A window picked by a fallback (folder match or last focus) that refuses connections (crashed, its discovery file left behind) is forgotten automatically and the call is retried once with the next window. The session's own window is never forgotten or replaced: if it refuses, the error says so; reload it (which also restarts the Claude session running in it).

  • A window is missing, or a discovery file has disappeared: the bridge writes one line to its stderr (which Claude Code keeps in its MCP server logs) when it skips a file. vscode-control: ignored stale discovery file <pid>.json (its pid now belongs to a newer process) means the window had crashed and its pid was reused; the file was deleted. vscode-control: ignored discovery file <pid>.json (its process was not running when this session started; not deleted) means the file was only left out of that session's calls; if the window is alive, reload it so it writes a fresh file, or start a new Claude session.

Uninstall

  1. code --uninstall-extension pearnaly.vscode-control

  2. claude mcp remove --scope user vscode

  3. Delete the folder ~/.vscode-control (on Windows %USERPROFILE%\.vscode-control), which holds the discovery files.

Limitations

  • open_file opens text only: binary files and files over 50 MB fail with a clear message.

  • reveal_in_explorer works only inside the window's workspace folders, and cannot show items hidden by files.exclude or explorer.excludeGitIgnore.

  • After a reveal without focus, focus goes back to the active editor group: the chat only when the chat is an editor tab.

  • Secrets: Claude Code shares the editor's selected text with the chat. After typing a secret, never select it, and Claude must never reopen that file with a selection.

  • Secrets: VS Code's Local History (on Windows %APPDATA%\Code\User\History, elsewhere the equivalent folder in VS Code's user data) keeps a copy of a saved secret file. Delete that entry too, or exclude the secret folder with workbench.localHistory.exclude.

  • WSL and dev-container windows are untested (Remote-SSH works, see Requirements).

Development

npm test (vitest), npm run typecheck, npm run build (esbuild: extension/dist/extension.js CJS, bridge/dist/index.js ESM). Only the pure modules are unit-tested; files importing vscode are checked by the smoke script and the manual checklist. npm run package copies the root LICENSE to extension/LICENSE (a generated, git-ignored copy) because vsce looks for it next to the extension manifest.

License

MIT, see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude Code to use VS Code's tools, including diagnostics, symbol renaming, command execution, file opening, workspace listing, semantic search/API reference, terminal context, and integrated browser page interaction. It lets Claude see and act on the user's VS Code window, including shared browser pages and Markdown Editor selections.
      MIT