dondai44423/bladebro: agentic browser driver built from the agent's perspective

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.

_{Bladebro drives Amazon, Reddit, Wikipedia, fills a form, and manages tabs — all through 5 tools. Click to play.}

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

MCP over stdio — point your agent at the binary:

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

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:

Auto-extract (extract=auto) — deterministic structural list extraction. For every element with 3+ children, groups by structural signature, scores by content value. Extracts title, URL, image, price, date, description. Site-aware: shopping sites get rating/reviews/availability, Reddit gets score/comments/author, GitHub gets stars/forks/labels. Verified on HN, Lobste.rs, Wikipedia, DuckDuckGo, StackOverflow, Reddit, GitHub, MDN, Amazon.

Collect (act collect) — native scroll+dedupe loop for infinite feeds. Auto-extract, dedupe by URL/title, scroll, repeat until max or no new items. ONE call, ONE artifact. Verified: 80 items from infinite-scroll test page, 0 duplicates.

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, blocking

Login persistence: save after login, load in a later session. Restores cookies + storage, then navigates to the site.

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":"user@mail.com"},
  {"action":"type","label":"Password","text":"secret"},
  {"action":"click","text":"Sign in"},
  {"action":"wait","condition":"element","text":"Dashboard","timeout":10}
]}

Use run instead of act batch when you need branching (if/else), loops (while), or state ops that change tabs.

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.

🏗️ Architecture

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 AND re-renders. No more "stale element" failures.

Three pillars:

• Stable refs (e1, e2, ...) — semantic anchors that self-heal across navigations and re-renders
• Structural fingerprints (fp=0xdeadbeef) — FNV-1a hash of ancestor chain, tag, children, identity attributes
• Deltas only ({ -x, +y }) — every action returns what changed, not the whole world

🧬 Re-render immunity

The #1 reliability gap in every other agent browser, solved.

When React, Vue, or Angular re-renders a component, the DOM nodes are destroyed and recreated. Every other agent browser loses all refs — the agent must recapture, re-identify elements, and re-learn the page. Bladebro doesn't.

Every captured element gets a structural fingerprint — an FNV-1a hash of its ancestor chain, tag, children, and identity attributes. When a re-render changes text (the sig changes) but preserves structure (the fingerprint is identical), the stabilizer rebinds the ref via fingerprint match instead of invalidating it.

Before re-render:  e2 button "Buy Now"     sig=button|Buy Now|1  fp=0xdeadbeef
After re-render:   e2 button "Buy Now v1"  sig=button|Buy Now v1|1  fp=0xdeadbeef  ← SAME fp
                   ↺ e2 (re-render survived)

The agent sees ↺ e2 (re-render survived) in the delta. The ref never died. The click works. No recapture needed.

No other agent browser does this. Playwright, Puppeteer, CDP wrappers, SerpAPI — all lose refs on re-render.

🧠 Self-improvement

Learns from every session. Compounds with use. Never degrades.

Two subsystems, both persisted in ~/.blade/knowledge/, both surviving machine restarts:

Domain knowledge base

Per-site consent dialog selectors, learned from successful dismissals. On known sites (confidence >= 0.7), Bladebro tries the stored CSS selector first — skips the full 20-line detection JS entirely. Falls back to full detection if the selector doesn't match. Learns from every successful dismissal.

Safety mechanics:

• Learn only from success. Never learn from failures.
• Confidence scoring is asymmetric: success +0.05, failure -0.15. Failures cost 3x more.
• Below 0.3 confidence AND 30 days old = evicted. Bounded at 2000 domains.
• Zero regression for unknown sites — falls back to full detection transparently.

Behavioral fingerprint

Biometric parameters generated once per installation with small random variations, reused forever. Same "person" types at the same speed, moves the mouse with the same style, has consistent reaction time — every session.

A bot detector tracking behavioral consistency across visits sees the same identity every time. Without this, every session looks like a different person using the same browser — a red flag.

Corruption recovery: corrupted files are deleted and regenerated. Atomic writes (.tmp then rename). Never half-written. Values clamped to human-like ranges on load.

🛡️ 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

5x more token-efficient than every competitor. The Live Page Model holds a persistent, compressed, ref-stable model of the page across tool calls. Every act returns a delta (what changed), not the full page.

Live head-to-head: Bladebro vs agent-browser

Tested on real sites with agent-browser v0.33.2 at its best (headed, system Chromium, persistent profile, custom UA) vs Bladebro v3.0.21 defaults.

Key findings:

• Stealth is the biggest gap. agent-browser gets flagged by PerimeterX even headed. Bladebro's behavioral biometrics (bezier mouse, movementX/movementY, micro-tremors, human typing cadence, no Runtime.enable) are built into the CDP layer. Not a config option.
• Token efficiency. Bladebro returns model + content + URLs in one navigate call. agent-browser needs separate open + snapshot + read calls.
• Noise folding. Bladebro folds nav/footer elements and shows "193 more" instead of listing everything. agent-browser dumps the full tree.
• Structured extraction. Bladebro has see extract=auto (template-free, site-aware JSON). agent-browser has no equivalent.

Stealth benchmark: Bladebro vs Camoufox

This is a pure stealth comparison, not an agent browser comparison. Camoufox is a patched Firefox for web scraping, not an agent tool. But since people ask, here's how they compare on detection sites.

Both tested headed, same machine, same network, no proxy. 8 detection sites.

Near equal on stealth. Both pass real-world bot protection. Both get masking flagged on Pixelscan (expected for any anti-detect tool, flagged our real browser too). Neither was blocked anywhere.

Camoufox is impressive considering their situation: a year-long maintenance gap, stale fingerprints, and they still match. Respect for that.

The difference: Bladebro ships this stealth out of the box as an agent tool. No setup, no config, no Python venv. npm install -g bladebro && bladebro mcp and you're behind 6 layers of behavioral biometrics on a stock Chromium. Camoufox needs Python, a venv, and a Playwright script to drive it.

⚠️ Gotchas

🧱 Honest limits

💖 Sponsors

Bladebro is open source and free to use. If you want to support it, consider sponsoring development.

One-time sponsorships are also welcome at any amount.

Email bhandaribishesh879@gmail.com to become a sponsor.

🔄 Update hub

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

Apache-2.0 | see LICENSE.