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

• 15 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
  • Skills — load_skill
  • 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 so vision-capable clients see pixels natively. PNG / JPEG / GIF / WebP / BMP are detected from the file bytes; large images are downscaled to a 2000 px long edge and at most 4.5 MB of base64 (GIF and BMP become PNG), and images that already fit are sent unchanged. No file-size limit; images above 64 megapixels are rejected. SVG stays text via read_files.
• Local Agent Skills — folders with a SKILL.md in .agents/skills of each workspace folder or in ~/.agents/skills (the location shared by opencode, DeepSeek Harness, and other agents). As in those harnesses, only each skill's name and description reach the AI up front, listed in the load_skill tool description; load_skill then loads the instructions, and the skill's other files, when a task matches. The list is rescanned on every new connection. Name a skill in chat (for example /deploy or "use the deploy skill") to make the AI load it; skills marked disable-model-invocation: true are loaded only that way.
• AGENTS.md — standing instructions are loaded automatically, as in pi, opencode, Codex, and DeepSeek Harness: ~/.agents/AGENTS.md, then every AGENTS.md from the enclosing git repository root down to each workspace folder. They go into the server instructions and, because some clients never show those, in front of each connection's first tool result. An AGENTS.md in a subfolder is sent once per connection, with the first read_files or apply_patch result that touches a file under it. Each block is capped at 32 KB (broader files are dropped first). Edits, deletions, and new files during a connection are passed on with the next tool result.
• Plan | Build mode — a two-way switch in the panel header, next to the status badge. Build, the default on every Bridge start, lets the AI edit files and run commands. Plan is read-only: the AI can read code and run allowlisted read-only commands plus project tests and builds (such as npm test and npm run build); apply_patch, send_command_input, and terminate_command stay in the tool list but fail with READ_ONLY_MODE. Switching takes effect immediately, and the AI is told in its next tool result.
• Loop guard — the same tool call with identical arguments 3, 5, or 8 times in a row gets a note asking the AI to change its approach or tell you what is blocking it (as in DeepSeek Harness); the call still runs.
• 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, continuous public-endpoint health, persistent toggle, sessions timeline with mini diffs, and an advanced card covering interface language, 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.

After a successful start, AgentBridge checks the public health endpoint every 10 seconds for Cloudflare Quick and Named Tunnels. One failure is shown as a network fluctuation; two consecutive failures mark the public endpoint unavailable while keeping the local Bridge running. Each monitoring pass has an 8-second total network budget. To avoid consuming ngrok's HTTP/S request quota while idle, ngrok is verified at startup and through Check now, without background polling. The Session footer shows a compact indicator, and Connection Settings shows timestamps and failure details. A later successful check clears the warning automatically. Monitoring reports status only and does not restart a live tunnel solely because of a transient health failure.

Configuration

The interface-language override is agentbridge.language; Bridge and tunnel settings live under agentbridge.bridge.*.

Interface language, managed shell, and link-routing controls also 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.