VSC AgentBridge

Expose your VS Code workspace's tools — files, terminal, LSP, diagnostics, and images — to web-based AI assistants that support MCP (GPT, Arena, etc.) over a public HTTPS tunnel.

中文文档 | README.zh-CN.md

Status

Published to the Visual Studio Marketplace. Built and tested on Windows with VS Code 1.95+ and Node 22+. All fourteen development phases are landed and verified end-to-end against ChatGPT Connectors.

Features

• 13 MCP tools spanning:
  • File system — read_files, apply_patch, search_files, find_files, list_directory, read_image_file
  • Terminal — run_command, get_command_output, send_command_input
  • LSP / diagnostics — get_diagnostics, lsp
  • Bridge state — set_todos, report_progress
• 3 tunnel providers — Cloudflare Quick Tunnel (default, zero-config), Cloudflare Named Tunnel (stable hostname), ngrok (reserved domain).
• 9 managed shells — Windows PowerShell 5.1, PowerShell 7+, cmd; POSIX bash, zsh, sh, fish. The description shown to the AI updates automatically when you switch shells.
• Vision-capable read_image_file — returns MCP ImageContent blocks (PNG / JPEG / GIF / WebP / BMP) up to 5 MiB so vision-capable clients see pixels natively. SVG stays text via read_files.
• External link routing — agentbridge.bridge.openInternalBrowser (auto / all / external) controls whether ChatGPT / Arena open inside VS Code's Simple Browser or in the OS default browser. Default auto matches the original in-editor experience.
• Bridge panel — Activity Bar view with tunnel provider radio, status hero, persistent toggle, sessions timeline with mini diffs, and an advanced card covering managed shell, link routing, copy-MCP-prompt, and reset routeToken.
• Auto-start — flip agentbridge.bridge.persistentMode to bring the Bridge up on extension activation.
• Client compatibility — verified against ChatGPT Connectors, Claude Desktop, Cursor, Cline, Continue.

Installation

Option A — From VS Code Marketplace (recommended)

The extension is published on the VS Code Marketplace, so you can install it directly from the Extensions panel.

1. Open VS Code → Extensions panel (Ctrl+Shift+X / Cmd+Shift+X)
2. Search VSC AgentBridge (or visit the Marketplace page)
3. Click Install

Or from the command line:

code --install-extension agentbridge.vsc-agentbridge

Option B — Download prebuilt vsix (offline / VSCodium)

For environments without Marketplace access (VSCodium, internal networks, manual installer distribution), grab the prebuilt vsix from GitHub Release and sideload.

1. Open the latest release page

2. Download the latest vsix release to your computer

3. Install it:

   code --install-extension /path/to/downloaded.vsix

   Or graphically: VS Code → Extensions panel → ⋯ menu → "Install from VSIX..." → pick the downloaded file.

Option C — Build from source (for developers)

Requires Node 22+ and npm.

git clone https://github.com/5258MF/AgentBridge.git
cd AgentBridge
npm install
npm run build

Then either run it as a dev extension or sideload the packaged vsix:

# Dev mode
"Code.exe" --extensionDevelopmentPath="$PWD"

# Or package a vsix locally
npx @vscode/vsce package --out vsc-agentbridge-latest.vsix --skip-license --allow-missing-repository
code --install-extension vsc-agentbridge-latest.vsix

Tunnel providers

Mode	Public URL stability	Requirements
cloudflare (default)	Ephemeral — changes after each restart	None
cloudflare-named	Stable hostname (mcp.example.com)	Cloudflare account, managed domain, Tunnel Token, published app route
ngrok	Reserved domain (you.ngrok-free.dev)	ngrok Authtoken + reserved hostname

Choose in the AgentBridge panel's tunnel provider radio, or set agentbridge.bridge.tunnelProvider in settings.json.

Configuration

All settings live under the agentbridge.bridge.* namespace.

Key	Type	Default	Notes
tunnelProvider	enum	cloudflare	cloudflare / cloudflare-named / ngrok
cloudflareNamedDomain	string	""	Fixed hostname (e.g. mcp.example.com)
cloudflareNamedLocalPort	integer	48271	Local port the named tunnel routes to
ngrokDomain	string	""	Reserved ngrok domain (e.g. you.ngrok-free.dev)
managedShell.windows	string	""	Absolute path (e.g. C:\Program Files\PowerShell\7\pwsh.exe); empty = Windows PowerShell 5.1 default
managedShell.unix	string	""	Absolute path or PATH-resolvable name (e.g. /bin/zsh or bash); empty = /bin/bash default (or /bin/sh when bash is unavailable)
openInternalBrowser	enum	auto	auto / all / external; controls whether external links open in VS Code Simple Browser or OS default browser
persistentMode	boolean	false	Start the Bridge automatically on extension activation

Runtime toggles for managed shell and open-internally-browser live on the Bridge panel's advanced card.

Cloudflare Named Tunnel walkthrough

See docs/cloudflare-named-tunnel-setup.md for a step-by-step guide (install cloudflared, create the tunnel, copy the token, add the route, verify DNS, start + verify the bridge). English version: cloudflare-named-tunnel-setup.en.md.

ngrok development domain walkthrough

See docs/ngrok-development-domain.en.md for a step-by-step guide (install ngrok → copy the fixed domain → configure Authtoken → check → start + verify). Chinese version: ngrok-development-domain.md.

Connecting the ChatGPT web app: see docs/chatgpt-web-connector.md (start Bridge → copy MCP address → add Connector → grant permissions). English version: chatgpt-web-connector.en.md.

Known limitations

• Cloudflare Quick Tunnel URL is ephemeral — rotates every restart. Use Named Tunnel (or ngrok) for stable, shareable URLs.
• Restricted networks (教育网 / strict-firewall campus networks) can hang Quick Tunnel. UDP/QUIC is often half-blocked. Work around it with HTTP2/http transport override and a routing rule to cloudflare.com in your proxy. Named Tunnel is the long-term fix.
• Simple Browser + ChatGPT login sometimes bumps into Cloudflare managed challenges. Multi-retry usually resolves; if it persists, switch to the OS browser via agentbridge.bridge.openInternalBrowser: "external".
• ChatGPT Connectors caches tools/list at session start. Adding / removing / modifying MCP tools requires the user to manually Refresh (or Remove + re-add) the Connector in chatgpt.com → Settings → Connectors. Stop+Start the Bridge alone is not enough.

Compatibility

• VS Code 1.95+
• Node 22+
• Verified on Windows. POSIX shell providers resolve paths via which(1).

License

MIT. See LICENSE for the full text.

Parts derived from microsoft/vscode are covered by that project's MIT license. See https://github.com/microsoft/vscode for details.