bladebro

Give your AI agent a browser. Few tools. Full control. Real stealth. Zero runtime deps.

Re-render-immune refs · batch actions · auto-extract · self-improving · 6-layer stealth

One MCP server · one persistent page model · zero Node.js · one binary · Linux · macOS · Windows

npm install -g bladebro && bladebro mcp

Install · The 5 tools · Architecture · Re-render immunity · Self-improvement · Stealth · Comparison · Gotchas · Limits

Bladebro is an agentic browser driver built from the agent's perspective. Instead of 20+ tools that each do one thing, Bladebro gives you 5 tools that together provide full control. It drives stock Chromium over CDP, holds a persistent Live Page Model across tool calls, and returns diff-first results: the agent sees what changed, not the whole world, every single time.

Built in Rust. One static binary. No runtime. No Node.js. No Playwright shim. Just the browser engine and your agent. Native on Linux, macOS, and Windows.

Speaks MCP 2024-11-05 through 2026-07-28: legacy initialize handshake and the new stateless per-request negotiation with server/discover, dual-dialect. Works with every MCP client, old and new.

What makes it different

🚀 Install

npm (recommended)

npm install -g bladebro
bladebro mcp

That's it. No Rust, no compilation, no dependencies. The npm package ships a prebuilt binary for your platform:

npm resolves the correct binary automatically via os/cpu fields. Users only download the binary for their platform. Zero postinstall scripts, zero warnings.

Pi coding agent

pi install npm:bladebro

That's it. The extension spawns the binary as a stdio MCP subprocess, discovers tools via tools/list, and registers them natively with pi via pi.registerTool(). The agent gets 5 first-class tools (browser.act, browser.see, browser.state, browser.run, browser.vision) — no adapter, no config files, no proxy tool.

Tool definitions come from the binary at startup, so they auto-adapt to any tool def changes with zero extension maintenance. Auto-updates via pi update --extensions.

From source

Prerequisites: Chromium or Google Chrome (auto-detected), Rust 1.86+. Linux: Xvfb for headless servers (macOS/Windows run headful natively).

git clone https://github.com/dondai44423/bladebro.git
cd bladebro
cargo build --release
./target/release/bladebro mcp

Connect your AI agent

Just tell your agent to add Bladebro to its MCP config. For Claude Desktop, Cursor, and most MCP clients, add this to your config file:

{
  "mcpServers": {
    "bladebro": {
      "command": "bladebro",
      "args": ["mcp"]
    }
  }
}

Using pi? One command, no config:

pi install npm:bladebro

Diagnostics

bladebro -doc    # system check (Chrome, Xvfb, profile, network, version)
bladebro -v      # version + update status
bladebro audit   # stealth verification

🎯 The 5 tools

act — act, then observe

Every act returns an outcome verdict + page delta. Click auto-escalates: mouse, JS, Enter. Click by text (no see needed): act click text="Sign in". Ambiguous text? Error lists matches with refs and nth values: retry nth=2.

Self-healing refs — stale refs re-resolve automatically. If e5 was "Sign in" and the page navigated, act click e5 finds the new "Sign in" and clicks it. You see [ref e5 healed] in the verdict.

Batch actions — run multi-step workflows in ONE MCP call. Fills, submits, multi-click sequences: one call, one final delta. Halts on navigation or first error with step-level context. 5-step form fill+submit in one call instead of 11.

url= on any action — act fill url="https://..." fields=[...] navigates first, then fills. One call to go to a page AND act on it. Exception: download fetches via JS (no navigation), set-cookie uses url for cookie scope.

slim=true — returns verdict only, no delta. Use when you know what happens next.

see — observe (rarely needed)

Navigate and act already return page state. Use see for: