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.

Related MCP server: vscode-mcp-server

Features

• 14 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, terminate_command

  • 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).

• Cross-platform cloudflared detection and installation — one-click Winget installation on Windows and Homebrew installation on macOS; Linux checks PATH, /usr/bin, and /usr/local/bin while keeping installation manual through Cloudflare's official instructions.

• Managed shell support matrix — PowerShell 5.1 / PowerShell 7+ (Windows), bash (Linux) and zsh (macOS) fully support run_command via per-prompt protocol hooks; cmd, sh and fish are rejected up front with a clear error instead of timing out. The syntax hint 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

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

cloudflared detection and installation

Cloudflare Quick Tunnel and Cloudflare Named Tunnel share the same cloudflared detection and installation help. The required flow is Check Tunnel → install if needed (with automatic verification) → Start Bridge. Every check actually runs cloudflared --version; finding a file that cannot execute does not count as an installed client. Manual Cloudflare starts stay disabled until the selected provider and configuration have passed a check; Persistent Mode performs that check automatically before starting. ngrok keeps its existing start behavior.

When a check cannot find cloudflared, AgentBridge also verifies whether Winget or Homebrew can actually run. The one-click install button appears only when that installer is available. A successful installation is checked automatically; Start Bridge unlocks only after the selected Cloudflare provider and its configuration pass verification. If Winget is missing on Windows, Homebrew is missing on macOS, or cloudflared is absent on Linux, open the official Cloudflare downloads instructions from the panel, install it manually, and click Check Tunnel again. This release does not run APT or modify Linux package sources.

Configuration

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

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 (check/install cloudflared, create the tunnel, copy the token, add the route, verify DNS, check, then 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.

• Cloudflare Tunnel requires outbound port 7844. cloudflared prefers QUIC over UDP 7844; TCP 7844 (HTTP/2) is the alternate transport. If a campus, corporate, firewall, or proxy network blocks both transports, neither Quick Tunnel nor Named Tunnel can connect; allow one of the 7844 transports, switch networks, or use ngrok instead.

• QUIC can stay unstable even when cloudflared's pre-check passes. The pre-check only probes short QUIC handshakes; networks that pass the handshake but drop sustained UDP flows (common on campus/corporate networks) keep failing real traffic, and cloudflared does not reliably fall back to HTTP/2 within its startup window. AgentBridge self-heals: with tunnelProtocol: auto (default), repeated edge dial failures with zero registrations restart the tunnel with HTTP/2 (TCP 7844) automatically and announce it in the panel; set tunnelProtocol: http2 to skip QUIC entirely.

• 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+

• Built and verified on Windows; macOS supports Homebrew installation, while Linux detects an existing cloudflared and provides a manual installation entry point.

• File search bundles ripgrep on Windows. On macOS/Linux it uses rg from PATH when available, otherwise the built-in bounded Node engine (content search: at most 20,000 files and files up to 2 MiB; file discovery: at most 5,000 candidates).

License

MIT. See LICENSE for the full text.

Third-party notices, including the MIT terms for portions derived from microsoft/vscode, are listed in THIRD_PARTY_NOTICES.md.