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.

Demo

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

🔌 Two ways to use Bladebro

Bladebro gives you the same 5 tools, same stealth, same page model through two interfaces. Pick one or use both.

Option 1: MCP Server

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

Option 2: CLI

The CLI has the exact same power as the MCP server. Same handlers, same stealth, same page model. Any feature update auto-propagates to both surfaces automatically.

How AI agents discover the CLI: bladebro help --json returns the same structured tool definitions as MCP tools/list, plus a CLI command mapping. An agent calls it once to learn the full interface, then uses --json on every command for structured output. No guessing, no parsing help text.

# Agent discovery: same schemas as MCP tools/list
bladebro help --json | jq '.tools[].name'
# ["act", "see", "state", "run", "vision"]

Daemon mode (persistent Chrome, zero startup delay after first launch):

# Start the daemon (Chrome stays alive across commands)
bladebro daemon

# All commands now connect to the daemon instead of launching new Chrome
bladebro nav https://news.ycombinator.com
bladebro see content
bladebro act click e5
bladebro see model --json | jq .text
bladebro state cookies
bladebro vision --marks
bladebro stop

One-shot mode (no daemon, launches Chrome per command):

bladebro see content https://example.com --no-daemon
bladebro nav https://news.ycombinator.com --no-daemon

All 5 tools work from the CLI:

# Navigate
bladebro nav https://example.com

# Read the page (6 modes: model, content, outline, extract, links, forms)
bladebro see model                   # interactive elements with refs
bladebro see content                # clean markdown
bladebro see outline                 # heading hierarchy
bladebro see extract auto            # auto-detect structured data

# Interact (20+ actions: click, type, fill, scroll, press, hover, ...)
bladebro act click e5                # click element e5
bladebro act type e12 "hello world"  # type text
bladebro act scroll 0 500            # scroll down
bladebro act press Enter             # press a key
bladebro act fill '[{"label":"Email","text":"a@b.com"},{"label":"Password","text":"secret"}]' --submit e20

# Manage state
bladebro state cookies               # list cookies
bladebro state tabs                   # list tabs
bladebro state open-tab https://example.com

# Batch actions
bladebro run '[{"action":"click","ref":"e5"},{"action":"type","ref":"e12","text":"hello"}]'

# Screenshot
bladebro vision                      # save screenshot to /tmp
bladebro vision --marks              # with numbered ref badges

# JSON output for scripts and agents
bladebro see model --json | jq .text
bladebro act click e5 --json | jq .is_error

Flags:

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

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.

✂️ Context pruning

54% fewer tokens over a browsing session, zero capability loss.

When an agent is in the middle of a multi-step interaction on the same page (click, type, scroll, click, scroll...), each act response includes the full page element list. After the first 2-3 turns, the agent already knows the page. The repeated element list is pure token waste.

Bladebro progressively compresses act responses on the same page:

Counter resets on:

• Navigation to a new page
• Any see call (agent is re-orienting)
• Any error (agent needs full state to recover)

Never compressed: see, state, vision, run responses. Only act is compressed, and only when the agent is repeatedly interacting on the same page.

Toggle:

bladebro state compress status   # check current state
bladebro state compress off       # disable
bladebro state compress on        # re-enable (default)

Or via environment variable: BLADE_NO_COMPRESS=1 disables at startup.

🧠 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 development, consider sponsoring.

One-time sponsorships are also welcome at any amount.

Pricing will increase as the project grows. Right now Bladebro is early (small but growing), so sponsorship is cheap. A Gold tier at $50/mo is high reward, near zero investment for any company that relies on browser automation. Lock in the current rate before it goes up.

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.