snapgent-connector

  ███████╗███╗   ██╗ █████╗ ██████╗  ██████╗ ███████╗███╗   ██╗████████╗
  ██╔════╝████╗  ██║██╔══██╗██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝
  ███████╗██╔██╗ ██║███████║██████╔╝██║  ███╗█████╗  ██╔██╗ ██║   ██║
  ╚════██║██║╚██╗██║██╔══██║██╔═══╝ ██║   ██║██╔══╝  ██║╚██╗██║   ██║
  ███████║██║ ╚████║██║  ██║██║     ╚██████╔╝███████╗██║ ╚████║   ██║
  ╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝      ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝

  > browser extension + local bridge for VS Code and MCP
  > no API key · no terminal · no copy-paste

snapgentV3 is a browser extension plus a local bridge that connects a normal AI chat to VS Code. It automatically uses the currently open workspace. Describe what you want in plain language — the extension forwards commands to the selected server through the local bridge, and returns the results to chat.

Free and open source — no API key, subscription, or sign-in required. snapgentV3 automatically uses the currently open VS Code workspace.

• Installation: Watch Installation Video
• Demo: Watch Demo Video

💻 VS Code

The default target. Automatically connects to the workspace currently open in VS Code.

01   How it works

┌─────────────┐     plain-text      ┌──────────────────┐    WebSocket    ┌────────────┐    MCP    ┌────────────────┐
│  AI chat    │ ───  commands  ───▶ │ snapgentV3       │ ──────────────▶ │  Bridge    │ ────────▶ │ Selected MCP   │
│  (browser)  │ ◀──  results   ───  │ browser extension│ ◀────────────── │ (local)    │ ◀──────── │ target         │
└─────────────┘                     └──────────────────┘                 └────────────┘           └────────────────┘

1. You describe a task in a supported AI chat.
2. The AI replies with a snapgentV3 command.
3. The extension detects the command and forwards it to the local bridge.
4. The bridge routes it to the VS Code MCP server.
5. The result is sent back into chat, and the AI continues working.

VS Code's MCP server is configured locally by start.bat; it detects the open VS Code workspace automatically.

02   Supported AI providers

Provider activation is configured in manifest.json (content_scripts and host_permissions) and PROVIDER_URLS in background.js.

03   Requirements

• Microsoft Edge or Google Chrome (Manifest V3).
• VS Code for the default target. Keep the workspace you want to use open in VS Code.
• Windows, macOS, or Linux for the bridge.
• Python 3.9+ on macOS and Linux. Windows includes the bridge executable.
• The bridge running while you use the agent.

04   Installation

① Load the extension

1. Download and extract the latest SnapgentV3 release.
2. Open edge://extensions (Edge) or chrome://extensions (Chrome).
3. Enable Developer mode.
4. Click Load unpacked and select the snapgent-extension folder.
5. The snapgentV3 icon appears in your browser toolbar.

② Set up the MCP target

For VS Code, open the project folder you want to work on before clicking Start in the chat bar. The bridge can be started before VS Code; the agent waits until a workspace is available and does not fall back to the Snapgent release folder.

③ Start the bridge

• Windows — double-click start.bat. It configures VS Code MCP automatically. You can start the bridge before VS Code. Machine-specific settings are written to the ignored local config.json.
• macOS — double-click MacOS_Start.command. It detects the bundled VS Code MCP server, Roblox Studio's MCP executable, and an installed EffectCraft CLI, then writes their machine-specific paths to the ignored local config.json. This launcher uses bridge.py; it does not run the Windows-only bridge.exe.
• Linux — open a terminal in the extracted release folder and run bash Linux_Start.sh. It detects the bundled VS Code MCP server and installed EffectCraft CLI, then writes machine-specific paths to the ignored local config.json. It uses bridge.py; the first launch installs websockets for your user, or creates a local Python environment if your distribution blocks user installs.

Keep the terminal window open while the bridge runs. On macOS, the first launch may show a Gatekeeper warning; select Done, then allow the script under System Settings → Privacy & Security.

Optional: connect EffectCraft

On Windows, start.bat detects EffectCraft in common install locations and starts its control channel automatically. On macOS, install the separate EffectCraft CLI release and put effectcraft-cli on your PATH; the launcher detects it and starts the app's control channel when EffectCraft is installed in /Applications or ~/Applications. On Linux, install the EffectCraft CLI and put effectcraft-cli on your PATH; the launcher detects it and starts EffectCraft when its executable is available on PATH or in a common installation location. On any system, save your work and close EffectCraft before restarting the launcher if EffectCraft is already open without the control channel. When the bridge connects, choose EffectCraft in the MCP target selector on the chat bar.

On macOS, Roblox Studio MCP is detected at /Applications/RobloxStudio.app/Contents/MacOS/StudioMCP; set ZS_STUDIO_MCP_PATH before launching if it is installed elsewhere. Linux does not auto-detect Roblox Studio MCP. If you have a compatible Linux MCP executable, set ZS_STUDIO_MCP_PATH to its path before running the launcher; Roblox Studio itself may not be available on your Linux distribution.

④ Start a session

1. Open a supported AI chat site and start a new chat.
2. Open a project folder in VS Code before clicking Start.
3. Click Start and describe what you want to make.

05   Usage

Once a session is running, just talk to the AI normally:

"Inspect the files in my project and explain how the login flow works."

"Add a search bar to the books page and wire it to the existing API."

The AI sends commands, snapgentV3 runs them in the selected target (VS Code by default), and the results appear in chat. You can give the AI another instruction at any time.

Tips

• Keep the bridge window open — closing it disconnects the agent.
• Keep your intended project open in VS Code; it is the default MCP target.
• On Arena, use Direct mode.
• If Gemini or Kimi stops using tools in a long session, remind it to use the snapgentV3 commands or start a new chat.

06   Architecture

The extension is split into a provider-agnostic core and per-site providers. The core talks to each AI site through the ZSProvider interface.

core/config.js              system prompt, feedback, tool categories
core/parser.js              snapgentV3 command parsing
core/main.js                agent loop, UI, session state
providers/<site>.js         site-specific selectors and chat integration
background.js               WebSocket connection to the local bridge
manifest.json               browser permissions and content scripts

The bridge routes commands to the configured MCP servers. Windows uses the bundled bridge.exe; macOS and Linux run the cross-platform bridge.py with Python.

07   Project structure

snapgent-full/
├── snapgent-extension/        # Load this folder as an unpacked extension
│   ├── core/                  # Shared prompt, parser, agent loop, and UI
│   ├── providers/             # Per-AI-site integrations
│   ├── background.js          # Local bridge connection
│   ├── manifest.json          # Manifest V3 configuration
│   └── test-*.js              # Smoke tests
├── assets/                    # Project images
├── setup-config.ps1           # Configures Windows MCP servers
├── setup-config.py            # Detects MCP servers on ma