vibesurfer

vibesurfer (vs)

A real browser for your local AI agent.

Why

I wanted agents to automate browser work. First try Playwright, second Puppeteer directly. Both fell back to CDP underneath. CDP dropped sessions. Playwright crashed on long runs. Chrome got heavier every minor version. The bug wasn't any of those. CDP and Chrome were built for humans staring at DevTools, not for an LLM in a loop.

A human watching DevTools wants pixel-accurate rendering, async events as they fire, the full DOM on demand. An LLM pays per token, blocks per response, can't afford an event firehose or a 4000-token DOM dump on every read. One Hacker News front page rendered through Playwright is around 2000 input tokens before the agent has done any actual work. The same flow through vibesurfer is around 50.

So vibesurfer. A native browser daemon in Rust with a wire designed for LLM callers. Reads return state tokens and tree deltas instead of full DOM. Writes check the token. Three real engines underneath (WKWebView on macOS, WebKitGTK on Linux, WebView2 on Windows); the protocol on top is small, synchronous, line-oriented.

For tasks that need pixels, vs capture takes a screenshot, vs viewport switches between mobile and desktop layouts, and vs layout returns bounding boxes. The default path is text in, structured deltas out.

Install

Homebrew (macOS, Linux):

brew tap frane/tap && brew install vibesurfer

curl:

curl -sSL https://raw.githubusercontent.com/frane/vibesurfer/main/install.sh | sh

From source:

git clone https://github.com/frane/vibesurfer && cd vibesurfer
cargo install --path crates/vs-cli

Linux needs WebKitGTK 6. Windows needs the WebView2 runtime (already on Windows 11, available for Windows 10 from Microsoft).

Wire it into your agent

The fastest path is the binary's auto-installer. After vs is on your PATH:

vs skill install

It detects Claude Desktop, Claude Code, Cursor, Codex CLI, Gemini CLI, and OpenClaw on your machine and writes the SKILL.md plus an MCP entry into each. Re-run after upgrading.

If you'd rather install per-agent, the manifests below are in the repo and supported by each tool's native plugin command:

Claude Code

/plugin install frane/vibesurfer

Resolves .claude-plugin/marketplace.json at the repo root and plugin/.claude-plugin/plugin.json. The plugin registers the MCP server (vs mcp) and ships the SKILL.md so Claude knows when to reach for it.

Codex CLI (OpenAI)

The plugin manifest at plugin/.codex-plugin/plugin.json declares the skills directory and the MCP entry. Install via Codex's plugin command, or do it by hand:

mkdir -p ~/.codex/skills && cp -r plugin/skills/vibesurfer ~/.codex/skills/

Then add the MCP server to ~/.codex/config.toml:

[mcp_servers.vibesurfer]
command = "vs"
args = ["mcp"]

vs skill install does both steps automatically.

Gemini CLI

gemini extensions install https://github.com/frane/vibesurfer

Reads gemini-extension.json at the repo root, which wires vs mcp as the server and points at plugin/GEMINI.md for the context file.

Claude Desktop or any MCP-aware agent

Edit the tool's MCP config (claude_desktop_config.json, Cursor's mcp.json, etc.) and drop in:

{
  "mcpServers": {
    "vibesurfer": {
      "command": "vs",
      "args": ["mcp"]
    }
  }
}

The same JSON sits at plugin/.mcp.json if you want to copy from the repo.

Short forms

Every primitive has a one-to-three-letter alias. Long forms exist for documentation; agent invocations should use the short form to save tokens.