Claude Desktop Bridge
One button connects Claude Desktop to your VS Code workspace over MCP. It uses Claude Desktop's
normal JSON config, so it works with the free app and needs no API key.
Claude can then read your project, edit files, check errors and run commands, and you watch every
step in the sidebar.
Use it
- Install the
.vsix (Extensions view, ... menu, Install from VSIX...).
- Open a project folder. The extension connects by itself on startup.
- Quit Claude Desktop completely and reopen it (on Windows: right-click its tray icon, then Quit) so it loads the new entry. This is only needed the first time.
- Ask Claude Desktop something like "look at the project in VS Code and fix the failing test".
The sidebar (bridge icon in the Activity Bar) has a single Connect / Disconnect button. Below it:
| You see |
What it is |
| Claude said |
The reason Claude gives for each call, its plan, findings and final summary |
| Views |
Every file, search, outline or git command Claude looked at, with a preview of what it saw |
| Edits |
Every file created, edited, moved or deleted, with the diff inline, +/- counts, and Diff, Open and Undo |
| Commands |
Commands Claude ran, with live output and the exit code. Background processes have a Stop button |
| Permissions |
A collapsible panel: pick a preset or set each group to Allow, Ask or Deny |
The chips above the feed (All, Said, Views, Edits, Commands) filter it. The same lines go to the
Claude Bridge output channel.
Viewing websites
Ask Claude to "check my site" or to look at a page. It calls browser_open, which shows the page in VS Code's
own browser so you watch along, and returns a short text preview. browser_read gives the page text and
browser_screenshot returns a real image (also shown in the sidebar feed).
How it works, best option first:
- VS Code's integrated browser tools (VS Code 1.110 or newer). Turn on
workbench.browser.enableChatTools
(the extension offers to do it). The extension reaches those tools through vscode.lm, so Claude Desktop can
use them. Claude reads the live page and can screenshot it.
- Simple Browser + a headless Chrome/Edge/Brave/Chromium. The page is shown in VS Code's Simple Browser, and
Claude reads it (after JavaScript runs) and screenshots it through the headless browser. Set
claudeBridge.browserPath if yours is not detected.
- Simple Browser + plain HTTP. The page is shown, and Claude reads the static HTML. No screenshots.
Claude Bridge: Show Browser Status prints which option is active and every browser tool VS Code has.
Pages are viewed through your machine, so localhost dev servers work. Only http and https URLs are allowed.
Saving tokens
Claude pays for the tool list in every conversation and for every result. The bridge keeps both small:
- Compact tool list: 42 tools in about 3,900 tokens (the first 37 tools used about 6,300).
- Compact results: colour codes, progress bars and repeated lines are folded in command output, pages and
searches; compact JSON; matches grouped per file; long logs keep their start and end. File contents are
never altered. Each request in the feed shows
~N tokens sent.
- Size cap:
claudeBridge.maxResponseChars (default 16000, about 4000 tokens). Larger results are cut with a
hint on how to ask for less. Switch everything off with claudeBridge.compactResponses.
batch runs up to 15 calls in one request, [["read_file",{"path":"a"}],["git_status",{}]], which saves
round trips (each one re-sends the whole conversation). Each call is still permission-checked and shown.
How it works
Claude Desktop --stdio--> bridge.js --127.0.0.1 + token--> this extension --> your workspace
reads claude_desktop_config.json
- Connect copies
bridge.js to ~/.claude-vscode-bridge/, adds a vscode-bridge entry under
mcpServers in claude_desktop_config.json (a .vscode-bridge.bak backup is made first; other
servers and settings are untouched), starts a local server on a random port and writes the port and a
random token to ~/.claude-vscode-bridge/connection.json.
- Claude Desktop starts
bridge.js itself. The tool list is available even when VS Code is closed;
calls need VS Code running.
- With several VS Code windows open, Claude talks to the one you used last.
Permissions
42 tools in 15 groups. Viewing is automatic by default; everything that changes something asks first
(Allow / Always allow / Deny). Pick a preset in the sidebar, with Claude Bridge: Permission Preset,
or fine-tune with Claude Bridge: Edit Permissions (shield icon) or the claudeBridge.permissions setting.
| Preset |
Meaning |
| Read only |
Claude can look and talk to you, nothing else |
| Ask before changes (default) |
Viewing is automatic; edits, commands and the rest ask |
| Auto-approve edits |
Edits and git commits go through; deleting, commands, background processes and the web still ask |
| Full access |
No prompts at all. Only in a project you trust |
| Group (default) |
Tools |
| View files (allow) |
get_workspace_info list_directory find_files read_file read_files search_text file_info get_diagnostics get_open_editors get_active_editor |
| Code intelligence (allow) |
get_symbols find_definition find_references |
| Git read-only (allow) |
git_status git_diff git_log |
| Editor, notes, questions (allow) |
open_file report_progress show_notification ask_user |
| Create and edit files (ask) |
write_file edit_file create_directory rename_path |
| Delete files (ask) |
delete_path (moves to the trash) |
| Run commands (ask) |
run_command (output returned, live in the feed) |
| Background processes (ask) |
start_background list_background read_background send_to_background stop_background |
| Visible terminal (ask) |
run_in_terminal |
| Git commits (ask) |
git_commit |
| View websites in the VS Code browser (ask) |
browser_open browser_read browser_screenshot browser_status |
| Download web pages, no browser (ask) |
fetch_url |
| Run any VS Code command (ask) |
run_vscode_command |
| Clipboard (ask) |
read_clipboard write_clipboard |
| Batch (allow; every call inside is checked on its own) |
batch |
Claude Desktop has its own approval list for each tool too. Both apply, so a tool needs to be allowed in each.
Safety rails: paths must be inside the open workspace (claudeBridge.allowOutsideWorkspace to relax),
writes into .git are refused, in an untrusted workspace (Restricted Mode) Claude may only look, never change or run anything, and the local server
only accepts connections that present the token (the connection file is readable only by you).
Settings
claudeBridge.autoConnect, permissions, allowOutsideWorkspace, approvalTimeoutSeconds,
maxReadKB, serverName, claudeConfigPath, nodePath.
Troubleshooting
- The sidebar icon is missing: run Claude Bridge: Open Panel, or right-click the Activity Bar and tick
Claude Bridge. The status bar entry at the bottom left always opens the panel too.
Older versions switched themselves off in Restricted Mode, which hid the icon after a restart; that is fixed.
- Nothing shows up in Claude Desktop: run Claude Bridge: Diagnose Connection. It also runs by
itself 25 seconds after Connect if Claude has not attached. It lists every config file it wrote to and
shows the end of Claude's own
mcp-server-vscode-bridge.log if Claude tried to start the bridge.
- Claude shows other local servers (for example Roblox_Studio) but not this one: Claude reads a
different
claude_desktop_config.json than the usual two. Run Claude Bridge: Find Claude Config
(it also runs once in the background after Connect). It searches your app-data and home folders by file name and by content,
lists every JSON that defines MCP servers, and adds the bridge to the ones Claude uses: a file that already lists a
server Claude shows (such as Roblox_Studio) is the one Claude reads. This includes Claude Code's ~/.claude.json.
A watcher puts the entry back if Claude rewrites its config, and Quit Claude Desktop Completely re-checks it after Claude closes.
- Quit Claude Desktop completely: Claude Bridge: Quit Claude Desktop Completely stops the tray and
background processes (Claude Code is left alone). Then open Claude Desktop again.
- Manual way: Claude Bridge: Copy JSON Entry for Claude Desktop copies a ready entry. Open Claude's
own Edit Config (Developer or Desktop app settings), paste it inside
"mcpServers", save, quit and reopen Claude.
- Still nothing, or you have no Node.js: install the bridge as a Claude Desktop extension instead.
Run Claude Bridge: Install in Claude Desktop as Extension (.mcpb), or double-click
vscode-bridge.mcpb (it is also saved in ~/.claude-vscode-bridge/) and click Install in Claude.
This does not touch claude_desktop_config.json and uses the Node.js built into Claude Desktop. Choose
"remove the JSON entry" afterwards so the bridge is not loaded twice (claudeBridge.registerInConfig).
Keep VS Code open with the extension connected; the sidebar flips to "connected" when Claude attaches.
- Windows: Claude Desktop from claude.ai/download is an MSIX package and reads its config from
%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json,
not %APPDATA%\Claude. Claude's own "Edit Config" button can open the wrong file. This extension
detects the package and writes to the right one. If your install is unusual, set
claudeBridge.claudeConfigPath.
- Claude rewrites its config: some Claude Desktop versions reset the file. The extension re-adds its
entry whenever VS Code regains focus; quit and reopen Claude Desktop afterwards.
- "is not valid JSON": the extension never overwrites a config it cannot parse. Fix the file and press Connect.
- No Node.js installed: the extension falls back to VS Code's own runtime. If you move or update
VS Code and the link breaks, press Connect again and restart Claude Desktop.
- Remove it: run Claude Bridge: Remove from Claude Desktop, then restart Claude Desktop.
Runs in local VS Code windows. Shell and git tools only work for local folders.
Develop
No dependencies and no build step. Press F5 to launch an Extension Development Host.
node test/bridge.test.js, extension.test.js, msix.test.js, features.test.js and browser.test.js run the tests without VS Code.
| |