vite-plugin-pilot

AI-Powered Browser Navigation for Vite — Bridge the gap between AI agents and browser runtime via file I/O.

A Vite plugin that lets AI agents (Claude Code, Cursor, etc.) see, interact with, and verify browser pages through a compact snapshot format and simple JS helper functions. No Puppeteer, no Playwright — just file I/O.

简体中文 | English

Features

• Zero Config — Drop-in Vite plugin, works with any Vite project (Vue, React, vanilla JS, etc.)
• Compact Snapshot — Page state serialized into ~80 lines of text, optimized for LLM context windows
• Multi-Instance — Each browser tab is independently tracked, switch freely with PILOT_INSTANCE
• Auto Reload — Browser auto-refreshes when dev server restarts
• Vue/React Aware — typeByPlaceholder dispatches input events for v-model compatibility
• Element Inspector — Alt+Click any element to generate a prompt with full context for AI agents
• Channel Server — Push prompts directly to Claude Code session via hook-based integration

Why Not Chrome DevTools MCP?

| | vite-plugin-pilot | Chrome DevTools MCP | |---|---|---| | Connects via | Dev server injection (SSE + file I/O) | Chrome DevTools Protocol (CDP) | | Requires CDP port | No | Yes (--remote-debugging-port) | | WPS Add-ins | Yes | No (no CDP access) | | Electron / embedded browsers | Yes | Maybe (needs CDP enabled) | | Remote debugging | Yes (browser on any device) | Limited (same network, CDP exposed) | | Framework awareness | Vue/React v-model, scheduler | DOM-only | | Zero external deps | Pure file I/O | Needs Puppeteer/CDP client |

vite-plugin-pilot works anywhere a browser loads your Vite dev server — no special browser flags, no network tunneling, no CDP access needed. Just open the page and go.

Installation

pnpm add -D vite-plugin-pilot
# or
npm install -D vite-plugin-pilot

Quick Start

Send the following to your AI agent (paste into Claude Code CLAUDE.md or Cursor .cursorrules):

Read https://raw.githubusercontent.com/2234839/vite-plugin-pilot/master/SKILL.md,
follow its instructions to install vite-plugin-pilot and configure yourself, then start testing browser pages.

Browser-to-Claude Code (Channel Server)

Push prompts directly from the browser to your running Claude Code session — no copy-paste needed.

1. Add .mcp.json to your project root:

{
  "mcpServers": {
    "pilot-channel": {
      "command": "node",
      "args": ["node_modules/vite-plugin-pilot/bin/pilot-channel.js"]
    }
  }
}

2. Add hook config to .claude/settings.local.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node node_modules/vite-plugin-pilot/bin/pilot-hook-channel.js"
          }
        ]
      }
    ]
  }
}

The "Send to Claude" button in the Alt+Click panel auto-detects whether the channel server is running. When you send a message, it will be automatically attached to your next Claude Code input.

How It Works

┌─────────────┐     HTTP API      ┌──────────────┐     SSE          ┌─────────────┐
│  AI Agent   │ ───────────────→  │  Dev Server   │ ──────────────→ │  Browser    │
│  (pilot.js) │                   │  (middleware) │                  │  (client)   │
│             │ ←───────────────  │               │ ←────────────── │             │
└─────────────┘   result + snap   └──────────────┘   POST /result   └─────────────┘
                                  │  .pilot/
                                  │  instances/  (file channel fallback)
                                  └──────────────┘

1. Agent sends JS code via HTTP API (one request, ~10-50ms response)
2. Server dispatches code to browser via SSE (real-time, zero polling)
3. Browser executes code and posts result back via HTTP
4. Agent receives result + snapshot + logs in one response (fallback: file I/O)

Playground

The project includes a multi-framework playground:

pnpm dev
# /vue/ — Vue 3 playground
# /react/ — React playground
# /html/ — Vanilla JS playground

License

MIT