⚡ Bladebro

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

Drive · click · type · scroll · stealth · settle · delta-first · one binary

One MCP server · one persistent page model · zero Node.js · runs on your machine

cargo build --release && ./target/release/bladebro mcp

Install · The 5 tools · Stealth · Comparison · Gotchas

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.

🔧 Install

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

That's it. Bladebro finds Chrome itself, launches it with stealth flags, and manages its lifecycle.

Connect your AI agent via MCP over stdio:

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

🎯 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.

slim mode | act 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:

Big data goes to files. Extracts over ~6KB are written to ~/.blade/artifacts/ and the response gives you the path + preview. Read the file.

state | cookies, storage, tabs, sessions

run | batch + branch + JS

All act fields work in steps (ref, text, label, nth, js, key, url, etc). Plus if and while control flow.

{"steps":[
  {"action":"type","label":"Email","text":"[email protected]"},
  {"action":"type","label":"Password","text":"secret"},
  {"action":"click","text":"Sign in"},
  {"action":"wait","condition":"element","text":"Dashboard","timeout":10}
]}

vision | screenshot (last resort)

Returns base64 PNG. vision marks=true overlays numbered ref badges on elements so you can say "click e5" after seeing the screenshot. The structural model is almost always better: cheaper, more reliable, gives you refs to act on.

🛡️ Stealth system

Six layers. All on by default. No config needed.

Verified against real detection sites:

Run bladebro audit to verify your own setup.

📊 Comparison

3-4x more token-efficient than every competitor. The Live Page Model is the core innovation: it holds a persistent, compressed, ref-stable model of the page across tool calls. Every act returns a delta (what changed), not the full page. Refs (e1, e2, ...) are stable semantic anchors that survive DOM mutations. No more "stale element" failures.

⚠️ Gotchas

🔄 Update hub

Set GITHUB_TOKEN for higher API rate limits. Set BLADE_NO_UPDATE_CHECK=1 to skip update checks.

🤝 Contributing

PRs welcome. See CONTRIBUTING.md. Run cargo clippy --release -- -D warnings and cargo test --release before submitting.

📄 License

MIT | see LICENSE.