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 · drive your own browser

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

npm install -g bladebro && bladebro mcp

Demo · Install · The 5 tools · Usage · Your browser · Stealth Bench V1 · Stealth · Adapters · Comparison · Gotchas & limits

Bladebro is an agentic browser driver — it gives an AI agent full control of a real browser through 5 tools, not thirty. Built in Rust on a self-built CDP transport: one static binary, no Node.js, no Playwright, no runtime. It holds a persistent Live Page Model across tool calls, so every action returns what changed — never the whole page again.

⭐ New — drive your browser. bladebro rb on switches every surface to your own Chromium-family browser — your profile, your logins, your display — with the page-injection layer off entirely: a real environment has no manufactured tells to catch. Everything driver-side stays on. Real-browser mode →

🎬 Demo

Bladebro doing real work on two bot-protected sites — Reddit and X.com — in under two minutes. Real navigation, real actions, real content back: comment trees, threads and timelines as clean structured output.

https://github.com/user-attachments/assets/f67d80cc-a0ae-447a-8848-e35fce67f378

🏆 Stealth Bench V1

Run against browser-use's Stealth Bench V1: 80 real production sites protected by 11 anti-bot vendors. Bladebro cleared 68 (85%) — above every provider on the published leaderboard (browser-use-cloud: 81%).

• Out of the box — one IP, no proxy, no captcha solver, no fingerprint rotation, no cloud. Stock Chromium with Bladebro's stealth layer on by default.
• Honest run — real navigation of the real 80 sites; an open-model agent acted as the browsing agent because there was no paid cloud access, and the deviations are disclosed in full. The defensive layer being measured is Bladebro's own.
• Where it stands — perfect on Cloudflare (22/22) and reCaptcha (6/6); cleared the two sites browser-use-cloud did not (Shape, Temu); one named gap: Akamai (3/6).

Full report and methodology → · Per-site results (CSV)

✨ What makes it different

🚀 Install

npm (recommended)

npm install -g bladebro
bladebro mcp

Requires Chrome/Chromium; prebuilt Linux binaries require glibc 2.28 or newer. No Rust or compilation. npm resolves the prebuilt binary for your platform — zero postinstall scripts. Update later with npm update -g bladebro.

_{Every release builds and passes CI on Ubuntu, macOS and Windows. Linux ARM64 and macOS binaries are cross-compiled from Linux with cargo-zigbuild.}

Pi coding agent

pi install npm:bladebro

Registers 5 native tools (browser.act, browser.see, browser.state, browser.run, browser.vision) from the binary's own tools/list — tool definitions auto-adapt to any change, with zero extension maintenance.

DeepSeek Harness (DSH)

Add Bladebro as a native plugin in the Web UI's Plugins page, or run:

dsh plugin --profile web add bladebro

pnpm 11 defaults to a one-day release-age delay, so an unversioned install immediately after a release can select an older package. To install this release, use dsh plugin --profile web add bladebro@4.3.0 (or enter bladebro@4.3.0 in Plugins). If your package manager explicitly enforces a stricter release-age policy, wait for its configured delay. Keep that policy intact.

Restart the profile and start a new chat. Desktop users can install bladebro from the same Plugins page. For terminal setup, enable Desktop's Manage dsh Command, fully quit the app, then use its bundled command:

dsh plugin --profile desktop add bladebro

Use Desktop's command for its profile; the npm DSH CLI cannot manage that app-owned profile. Open Desktop again after installation.

DSH discovers the five tools as mcp__bladebro__act, see, state, run and vision (each with the same prefix). Schemas and descriptions come from the binary; DSH handles permissions, image attachments, reconnection and cleanup through its native MCP bridge. DSH may also expose its own generic MCP resource helpers and choose PTC presentation. No API key, separate MCP configuration, global Bladebro install or extra plugin package is needed. Chrome/Chromium must be installed on the machine running the DSH host. A remotely hosted Web UI controls that host's browser, rather than the device viewing the UI.

Disable/re-enable the Bladebro bundle in Plugins, or remove it with dsh plugin --profile web remove bladebro (use desktop with Desktop's command). Restart the profile and begin a new chat after package changes. Other tools and settings remain intact. Do not also configure a second MCP server named bladebro; DSH refuses the duplicate namespace.

Updates use DSH's package manager: dsh plugin --profile web update bladebro, or Update in Plugins. The plugin and native binary travel in the same package, so ordinary Bladebro releases update both. Existing global/Pi installs are separate. No background downloader or installation scripts run.

Advanced configuration belongs in the profile's cordis.patch.yml:

- id: bladebro
  config:
    # Optional absolute source-build/portable executable; package binary is default.
    binaryPath: /absolute/path/to/bladebro
    env:
      CHROME_PATH: /absolute/path/to/chrome
      BLADE_HOME: /absolute/path/to/private/browser-data
    toolCallTimeoutMs: 180000

Windows YAML paths can use forward slashes, such as C:/Tools/bladebro.exe. The optional cwd and reconnect settings use DSH's native MCP configuration. The default per-call budget is 180 seconds; raise it for longer run sequences. Cancellation stops waiting, but an already-dispatched browser mutation may finish: observe its destination before trying it again.

The npm CLI keeps its Node.js >=14 requirement; the DSH plugin uses the host's Node.js requirement. Prebuilt binaries cover Linux x64/ARM64 (glibc >=2.28), macOS Intel/Apple Silicon and Windows x64. Other targets need a source build and binaryPath. See the official DSH plugin commands and Desktop command runtime.

Hermes Agent

npm install -g bladebro
bladebro hermes on

Requires a current Hermes CLI with config get --json --raw, config unset and mcp test; update Hermes if those commands are unavailable.

Start a new Hermes chat (restart a running gateway or desktop client). This connects the standard MCP server and removes Hermes' built-in browser toolset, including browser_exec, from the agent's tools. Web search and extraction keep their existing settings. Chrome/Chromium must be installed; bladebro doctor checks browser prerequisites.

bladebro hermes status          # inspect the setup
bladebro hermes off             # restore the previous browser settings
bladebro hermes on --profile work  # target a named Hermes profile

Use the same profile for off; HERMES_HOME is also respected. If Hermes isn't on PATH, add --hermes /path/to/hermes (its CLI executable on Windows). Setup uses Hermes' public config and mcp test commands, saves private recovery state beside config.yaml, and reads settings back after writing. Interrupted switches can resume with on or restore with off. A changed MCP entry is refused during recovery rather than overwritten. Existing server environment settings are retained; explicit BLADE_HOME and CHROME_PATH from setup are forwarded because Hermes filters inherited variables. Other settings and pre-existing browser suppression survive restore. Avoid concurrent manual configuration edits while switching.

There is no separate plugin or copied tool schema: normal Bladebro updates update the Hermes browser too. Hermes may expose MCP tools through its built-in Tool Search; all five remain discoverable there. browser.backend: off selects Hermes' alternative native browser stack; it does not disable browser tools. See Hermes browser documentation and MCP documentation.

From source

Requires Chromium or Chrome (auto-detected) and Rust 1.86+. Linux servers need Xvfb for headful.

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

Source builds self-update too: bladebro -u swaps in the official released binary for your platform (it doesn't rebuild — for that: git pull && cargo build --release).

🎯 The 5 tools

act — do, then observe

Every call returns an outcome verdict + page delta. Clicks choose a role-aware activation lane and dispatch once; a quiet DOM never triggers another click. After a disconnect, mutating actions report an unknown outcome so the agent can inspect the destination before repeating them; clicking by text skips the read step (act click text="Sign in"), and ambiguous text returns matches with refs + nth values. Verdicts report observable evidence only: a state-only change is labeled state-only, no nodes added/removed (never a phantom (+0 −0)), an occluded click names what actually receives it, and a coordinate click that hits nothing names the topmost element at that point.

• Self-healing refs — a dead ref re-resolves by identity: act click e5 after navigation finds the new "Sign in" and reports [ref e5 healed].

• Batch — one call fills, submits, clicks; it continues through navigation and stops on the first error with step number + page state.

• selector= everywhere — click, hover, type, press, wait, select, clear, read, upload, eval, fill fields, and batch/run steps all accept a CSS selector (light DOM + open shadow roots); nth= picks among matches.

• url= on any action — navigate first, then act: act fill url="https://..." fields=[...] reaches a page and fills it in one call.

• slim=true — successful actions return verdicts only, including navigate/fill. On batch/run it inherits through steps and branches, preserving reads and failure recovery; a run step can set slim:false to opt back in.

• Unambiguous targeting: equally ranked text/label matches refuse with candidate refs/context. Choose ref, a unique selector, or nth (1-based). Targeted press focuses and checks its target before keys; an omitted target uses current focus.

• Popups: _blank clicks report the new tab ID once and restore the opener. Use state switch-tab to act in the popup. Input reactivates the addressed tab; no mutation is retried after a timeout.

• Waits: act wait selector=".ready" waits for visible CSS across open shadows/same-origin frames. condition=element text="Ready" also finds ordinary visible elements. condition=network requires 300ms with no tracked requests (long-lived streams excluded), and times out honestly. A false if/while may exit before its maximum budget.

• Pagination: act paginate next="text=Next" max=5 extract="auto" reads the current page, clicks once per advance and stops at missing Next, repeated data or the cap. The result retains each page and discloses partial completion. next also accepts a CSS selector, label=... or ref=...; max is 1–100 pages.

• HTTP body save: act download url="https://example.com" body=true saves an HTTP response (up to 32MiB/30s), reports status/final URL/path, and uses no browser cookies or JavaScript. It honors HTTP(S) BLADE_PROXY; other configured proxy types refuse before sending. The ordinary download path remains the browser-context attachment path.

see — observe

• Truncation is deterministic: output ends with …(N more: X link, Y button) — roles sorted by count desc, then alphabetically; the full set stays available via see filter=.
• Artifact JSON paging: next_offset:0 in an offload envelope means start at offset zero. Default pages are valid JSON envelopes whose data is a character fragment: concatenate the strings, then parse the payload. see artifact="<path>" items=true offset=0 limit=50 instead returns independently usable rows from a JSON array or items/data array; offsets count rows, next_offset:null means done. Item pages are capped at 500 rows/200KB; oversized individual rows require character paging.
• Big data goes to files. Payloads over 12KB are written to artifacts/ and returned as a path + preview; read any artifact back in pages with see artifact="<path>" (+offset/limit) — no filesystem access needed.
• Site-aware: on Reddit post pages and X.com status pages, extract=auto attempts the full comment tree / thread in ONE call; complete/partial and fallback notes disclose API blocks or missing replies; Hacker News rows carry points, author, age and comment count.

state — cookies, storage, tabs, sessions

run — batch + branch + JS

{"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 instead of act batch when you need branching (if/else), loops (while), or state ops that change tabs. see steps read inline — nav + loop + read across pages in ONE call. Steps take optional: true (a tolerated failure reports failed (optional) and the run continues), and wait accepts an else: [...] fallback branch when its condition times out.

vision — screenshot (last resort)

Screenshot as PNG; marks=true overlays numbered ref badges. MCP returns it as an image; the CLI writes a file and reports image_path. The structural model is almost always better: cheaper, more reliable, and it hands you refs to act on.

🔌 Usage

Same 5 tools, same handlers, same stealth — two surfaces. Use MCP for agents; use the CLI for scripts, shells and CI. One codebase, so every fix lands on both.

MCP server

Add to your client's config:

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

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

CLI

bladebro help --json is the single self-teaching manual: the same tool schemas as MCP, plus per-command usage, universal flags, payload conventions and exit codes — in ONE call.

bladebro help --json | jq '.tools[].name'   # ["act","see","state","run","vision"]
bladebro help act --json | jq .detail.actions

Daemon mode — the first command auto-starts a daemon; Chrome stays alive across calls:

bladebro nav https://news.ycombinator.com
bladebro see content
bladebro act click e5
bladebro stop                              # clean shutdown

bladebro see content https://example.com --no-daemon   # one-shot: launch Chrome per command

Universal flags

Exit codes are the contract: 0 success · 1 command failed (the text carries page state for recovery) · 2 usage error (the message says how to fix it).

Big payloads come from a file or stdin — no shell-quoting games: bladebro run @steps.json, cat steps.json | bladebro run -, bladebro act eval @script.js.

# Forms — one call
bladebro act fill '[{"label":"Email","text":"a@b.com"},{"label":"Password","text":"secret"}]' --submit e20

# Batch steps from a file
bladebro run @steps.json
bladebro act batch @steps.json

# Read + extract
bladebro see model --json | jq .text
bladebro see extract auto --json

# State
bladebro state cookies
bladebro state open-tab https://example.com

# Drive your own browser
bladebro rb on && bladebro nav https://news.ycombinator.com

# Screenshot with ref badges
bladebro vision --marks --json | jq -r .image_path

🧠 How it works

The core is the Live Page Model — a persistent, compressed, ref-stable model of the page held across every tool call. Three pillars:

• Semantic refs (e1, e2, …) — anchors assigned by signature (framePath|role|name|rank), not position. They survive scrolls, insertions and re-renders.
• Structural fingerprints — an FNV-1a hash of the ancestor chain, tag, children and identity attributes: the mechanism behind re-render immunity.
• Deltas only — every action returns what changed, so the agent never re-reads what it already knows.

Everything is built from scratch where it counts — the CDP transport, perception, stealth injection, biometrics, session management. Chromium is the only borrowed part.

🧬 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 — and every other agent browser loses its refs. Bladebro re-binds them: when text changes but structure survives, the ref follows the fingerprint instead of dying.

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 click works. No recapture. Playwright, Puppeteer, CDP wrappers, accessibility-tree snapshots — all lose refs here.

🪙 Token efficiency

5× more token-efficient than every competitor.

• Delta results — 60–570 tokens per action; snapshot-based tools spend ~1,400–2,000+.
• Tool defs — ~1,900 tokens vs 8,000–13,700. The agent plans; it doesn't juggle APIs.
• Context pruning — act responses compress after turn 3 on the same page: full (8K) → reduced (3K) → verdict-only (500 chars). ~54% fewer tokens over a session, zero capability loss.

bladebro state compress off     # on / off / status — or BLADE_NO_COMPRESS=1

The counter resets on navigation, any see, or any error. see, state, run and vision are never compressed.

🥷 Stealth

Six layers, all on by default, no config needed:

Verified against real detection sites:

Run bladebro audit to verify your own setup; run python3 tools/diff_oracle/oracle.py before any release.

🌐 Real-browser mode

The strongest fingerprint is a real one. No manufactured coherence to maintain — this lane simply is your browser, on your machine, with your history.

The stealth layers above manufacture coherence inside an isolated browser. The real-browser lane deletes the problem instead: it drives your own Chromium-family browser — your profile data, your display — and switches the page-injection layer off entirely. Truth has no tells to catch, so on this lane the amount of page patching is zero. Everything driver-side still runs: perception, Live Page Model, refs, adapters, token efficiency, resource blocking, biometrics + idle hum.

bladebro rb on        # switch every surface (CLI, daemon, MCP) to your browser
bladebro rb status    # what is configured / live (--json for agents)
bladebro rb pause     # manual control: input, navigation, history, downloads, collecting and tab ops refuse until `rb resume`
bladebro rb off       # back to the isolated agent browser

Supported browsers: Chromium, Google Chrome, Brave, Helium, Edge, Vivaldi, and Opera. bladebro rb use lists detected installs; bladebro rb use helium selects Helium on Linux, macOS, or Windows. On Linux, Helium wrappers on PATH and HELIUM_CONFIG_HOME are recognized. For an AppImage or portable install, launch Helium once to create its profile, select it, then set bladebro rb use --binary /absolute/path/to/helium.AppImage (or executable).

rb mode auto (default) attaches when a live endpoint exists, else clones. Browser override: rb use <id> · custom binary (nix/flatpak wrapper): rb use --binary <path|auto> · profile pick: rb profile <key> (validated; an absolute profile path also works) · re-import: rb refresh · wipe the imported copy: rb forget · rb visible on|off (real window vs --headless=new) · rb idle-hum on|off · rb idle-shutdown on|off (may the idle timeout close the real browser — default off). Switching restarts the daemon, and a live MCP/daemon browser is detected as stale at its next use and relaunched automatically; an attach session detaches instead — your browser is left running, untouched. No host restart anywhere.

⚠️ The agent browses as you: anything it does is attributable to your identity. rb on prints exactly what it will use and how to revert.

🧩 Site adapters

Built-in, automatic, zero config — and zero cost to the tool definitions. Adapters are runtime heuristics: they add no tools and no parameters, and their extra fields appear only on pages that have them.

• Reddit — see extract=auto on a post attempts the full comment tree in ONE call (API denial returns a clearly partial DOM fallback): every reply (collapsed included), thread-ordered with depth, author/date, fuzzed_score (Reddit's displayed values, labeled as such), full text, an op flag on the submitter's comments, and honest count/total/complete fields. sort=confidence|top|new|controversial|old|qa overrides the active/URL sort for a Reddit post. Safe transient GET failures have two bounded retries; policy denials and rate limits stop without switching hosts. On feeds: typed posts (title, fuzzed_score, comments, author, subreddit, date, domain). see mode=content gives clean title/meta/body markdown.
• X.com (Twitter) — see extract=auto on a status page returns the FULL conversation in ONE call: the focal post plus every reply and nested reply, thread-ordered with depth, author/date/counts, media and an op flag — read from the page's own API traffic (query ids captured live, self-healing across deploys). Profile/search/home return timelines the same way; search falls back to bounded in-page collection when X gates its API. The composer works through the normal tools: act click Reply → act type → act click Post.
• GitHub — repo pages: description, stars, forks, language, topics; issue/PR lists: number, title, status, labels, author per row.
• Product pages — price (with strikethrough original), rating, availability, key features — on any shop, not a fixed list of stores.

Adapters self-improve through the domain knowledge base (below): consent selectors, block history, settle timing and resource-blocking choices are learned per domain and reused on later visits. No plugin API — site-specific behavior belongs in the heuristics, not in config.

🌱 Self-improvement

Learns from every session, persists in knowledge/ under your data root, survives restarts.

Domain knowledge base — per-site consent selectors and behavior, learned from success only:

• Confidence +0.05 per success, −0.15 per failure (failures cost 3×). Auto-applied at ≥0.7, so known sites skip the full detection JS entirely.
• Evicted below 0.3 after 30 days; bounded at 2,000 domains. Unknown sites fall back to full detection — zero regression.

Behavioral fingerprint — biometric parameters generated once per installation and reused forever, so detectors see the same "person" every session: click precision, mouse curvature, typing cadence, inter-action gaps, overshoot and idle-hum frequency, all clamped to human ranges, written atomically.

📊 Comparison

Head-to-head: Bladebro vs agent-browser

agent-browser v0.33.2 at its best (headed, system Chromium, persistent profile, custom UA) vs Bladebro defaults, same machine:

🚧 Gotchas & limits

Honest boundaries: what surprises people, and what Bladebro deliberately does not do.

🔧 Configuration

Everything optional; configuration is environment variables.

Data & profile

Identity & stealth

Behavior & ops

Data root resolution (Unix): BLADE_HOME → $XDG_STATE_HOME/blade → $HOME/.local/state/blade → $HOME/.blade (legacy). Existing installs keep their tree — nothing is ever split across two directories. Windows: %USERPROFILE%\.blade (plus BLADE_HOME). bladebro doctor prints the resolved data root and exits nonzero when a required check fails. An explicit CHROME_PATH must point to an executable file; invalid overrides report an error instead of silently launching another browser.

Raspberry Pi OS trixie (arm64): issue #45 reports Chromium's regular-profile network service hanging even on loopback. On a detected Raspberry Pi running Debian/Raspbian trixie, the agent lane automatically uses one managed incognito context. Other hosts keep their persistent profile, and an explicit BLADE_PROFILE_DIR keeps its chosen mode. Set BLADE_INCOGNITO=1 to request this compatibility path elsewhere, or 0 to disable automatic selection. The real-browser and external-attach lanes keep their existing behavior. Incognito cookies still persist through Bladebro's login snapshot; named state save/load sessions restore cookies and storage. History, cache and automatic localStorage persistence are unavailable in this mode; launch diagnostics and doctor disclose that tradeoff. The reporter verified the Pi workaround; the release regression suite exercises the context, tabs, HTTP navigation and persistence contracts on Linux x64.

🔄 Maintenance

One updater per install — use the one that matches how you installed. npm-managed (npm install -g bladebro) → npm update -g bladebro, which keeps the shim, the platform package and npm's bookkeeping in sync. Everything else — a downloaded binary, a manual copy, a cargo build — → bladebro -u: it downloads the official released binary for your platform, SHA-256-verifies it against the published checksum, confirms it starts, backs up the old one and swaps it in; bladebro --rollback undoes it. (-u never rebuilds from source — for that: git pull && cargo build --release.)

bladebro -u knows which install it's on: under npm it refuses to touch npm's files and points you to npm (--force overrides — at the cost of npm's metadata going stale); on a build that's ahead of the latest release it won't downgrade without --force. BLADE_NO_UPDATE_CHECK=1 skips update checks entirely.

💖 Sponsors

Bladebro is free and open source. Sponsoring keeps development independent.

How to sponsor. GitHub Sponsors is enabled and featured on this repo — but my region isn't supported for payouts yet, so the reliable route is email: bhandaribishesh879@gmail.com. Write me, I'll share my PayPal, and we go through the steps. One-time sponsorships are welcome at any amount — Ko-fi covers quick one-offs too.

Prepay to lock your rate. You can pay for any number of months in one go at today's price, and that rate is fixed for the whole term — e.g. 6 months of Gold at today's $60/mo = $360, and a later increase (even to $150) doesn't touch it. Price changes only ever apply to sponsorships started after them.

🤝 Contributing

PRs welcome — see CONTRIBUTING.md. Before submitting: cargo clippy --release -- -D warnings and cargo test --release.

Using a coding agent? Point it at AGENTS.md — repo mechanics, house rules and verification instruments in one file.

📄 License

Apache-2.0 — see LICENSE.