BrowserClaw

Why BrowserPaw

BrowserPaw runs as a Chrome MV3 extension plus a local Native Messaging bridge. It uses the browser profile you already have instead of copying profile data or starting a separate automation browser. MCP clients can inspect pages, act with bounded tools, and verify results without making a remote service the owner of your browser session.

The project separates three things that are often mixed together:

• Static operating guidance that teaches an agent how to use BrowserPaw.

• Durable task and page ownership, so parallel work does not silently take over user pages.

• Verified site skills, which are learned from successful tasks and reused only after independent validation.

Related MCP server: OpenBrowser

⚡ What is BrowserPaw?

BrowserPaw is a Chrome extension and local MCP server. Its canonical tool names start with chrome_*, while each client may add its own namespace around them. The default core tool profile keeps discovery small; use CHROME_MCP_TOOL_PROFILE=full or chrome_tool_docs when a task needs the wider surface.

Two execution paths are available:

1. Deterministic tools and pipelines for indexed actions, forms, keyboard, uploads, downloads, screenshots, network work, and assertions.

2. chrome_act_toward_goal for a bounded local perception-action loop when an on-page goal is easier to describe than to decompose into every step.

The persistent browserpaw repl exposes the same execution service as small task, page, locator, skill, and help interfaces for multi-step code workflows. It is a documented BrowserPaw subset, not a claim of full Playwright compatibility.

🎯 Key capabilities

• Session reuse – Runs against the profile already open in Chrome; BrowserPaw does not copy your browser profile or move credentials into a second browser.

• Pruned, indexed DOM – chrome_read_dom assigns document-scoped references and reports action budgets, frame coverage, omitted regions, and truncation. A fast snapshot prioritizes the viewport and interactive targets.

• Strict, frame-aware actions – Explicit frame targets stay within that frame; ambiguous matches are rejected; nested OOPIF coordinates are projected through their actual renderer geometry.

• Card flattening and viewport virtualization – flattenCards collapses repetitive feed cards into one-line summaries; virtualizeViewport folds off-screen list items into count placeholders.

• Shadow DOM traversal – Recursively walks open shadow roots; closed shadow hosts are tagged and interacted with at the host level. Accessible names are extracted from icon-only buttons (aria-label, title, SVG titles).

• Batch and form pipelines – Run multi-step click/fill/wait/assert/extract sequences with one mutation budget and explicit partial or unknown outcomes.

• Overlay dismissal – chrome_dismiss_overlay closes marketing popups, cookie banners, and modals in one step, without dumping the DOM.

• Delta observations – Request DOM changes together with an action instead of paying for a separate full snapshot after every step.

• Native event fidelity – Clicks and keystrokes are dispatched as trusted CDP events (isTrusted: true), so React/Vue/Angular and Shadow DOM handlers fire normally.

• Action outcomes – Results distinguish pre-dispatch rejection, dispatched, unknown, and verified or unverified postconditions. Unknown mutations are never silently replayed.

• Coordinate fallback – When DOM indexing fails (canvas, WebGL, unknown custom UI), screenshots and chrome_computer provide a documented visual path.

• Adaptive viewport and screenshot budget – Owned pages follow the real Chrome window size and device pixel ratio instead of a forced 1440×900 frame. Inline screenshots default to an aspect-preserving 1568px/1.15MP JPEG budget for OCR and token balance; savePng writes a full physical-resolution PNG. Screenshot output is PNG/JPEG only, never WebP.

• Human handoff – chrome_request_human_intervention dims the page, shows a banner, and parks the cursor so the user can complete 2FA or captchas; automation resumes afterward.

• Task ownership and learning – Durable tasks track borrowed, newly opened, handed-off, and temporary pages. Verified site skills are stored in the Native library and shared by every connected client.

🧠 Interactive micro-loop

┌─ Macro Planner (your reasoning LLM) ───────────────────┐
│  Task decomposition, cross-page strategy, recovery     │
└───────────────────────────┬────────────────────────────┘
                            │ MCP (low frequency)
                            ▼
┌─ Semantic Micro-Loop (Native Server) ──────────────────┐
│  chrome_act_toward_goal:                               │
│  perceive → decide (enabled model) → act → verify   │
│  No MCP round-trip per step                            │
└───────────────────────────┬────────────────────────────┘
                            │ Native Messaging
                            ▼
┌─ Chrome MV3 Extension ─────────────────────────────────┐
│  canonical tools · CDP events · in-page engine         │
└────────────────────────────────────────────────────────┘

Routing guideline:

• Fixed action sequence, known indices → deterministic tools (chrome_batch_actions, chrome_form_pipeline).

• Single-page goal in natural language → chrome_act_toward_goal.

• Long-horizon, multi-page, novel, or escalated situations → the calling agent drives.

Ordinary click, fill and named-target tools resolve targets deterministically first. Supported non-exact text, label and named-role misses may use one bounded semantic decision when a model is enabled. Exact selectors, explicit references, coordinates, frame boundaries and actionability remain strict. Input values stay separate from target descriptions.

The optional micro-loop remains bounded (default 10, maximum 60 steps). It selects complete action-target candidates, stops on uncertain delivery, and requires independent read-only verification before reporting completion. Automatic submission is limited to explicitly requested searches on identified search controls. External writes return to the calling agent.

Model modes:

• Off: No semantic inference or model preload. Deterministic tools remain available; the autonomous micro-loop is hidden from tool discovery and rejects direct execution.

• Local: Uses the separately installed local decider. Availability, accuracy and performance are evaluated independently from TypeSafe Jev.

• Remote: Uses the configured TypeSafe endpoint and model. Set TYPESAFE_API_KEY or configure the Native service through the popup. Candidate descriptions and relevant context go to that endpoint; do not put secrets in locator descriptions.

• Failures: BrowserPaw preserves your selected backend. Temporary network, timeout and rate-limit failures pause inference for 30 seconds; the next use can resume the same backend without replaying the failed operation. Authentication/configuration faults require a correction; saving a corrected configuration restores the previously selected mode. A deliberate Off selection stays off, including after restart. The popup follows Native state.

• Existing remote vision: Remains experimental and capability-gated before screenshot capture. The concrete release returned by the endpoint determines eligibility; an alias alone does not establish image support. Coordinate freshness and consent checks remain required.

See semantic interaction and bounded goals for limits, verification, recovery and learned-skill boundaries.

🚀 Quick start

1. Build the bridge and load the extension

git clone https://github.com/GoldenLoaf24h/browserpaw.git
cd browserpaw
pnpm install
pnpm build
node app/native-server/dist/scripts/register-dev.js

Open chrome://extensions, enable Developer mode, and load app/chrome-extension/.output/chrome-mv3. A prebuilt extension, release installation, Windows details, Jev configuration, and troubleshooting are covered in INSTALL.md.

2. Connect a client

Every client ultimately talks to the same local BrowserPaw Native service and therefore shares tasks, page ownership, and verified site skills.

3. Install the operating skill

For an ordinary Agent Skills client, install the packaged, client-neutral skill:

browserpaw skill install

The default destination is ~/.agents/skills/browserpaw. --target names a different skills root, so the final directory is always <target>/browserpaw. --force only replaces an existing BrowserPaw install that carries its ownership marker.

4. Verify

browserpaw doctor
node skills/browserpaw/scripts/doctor.mjs

Claude Code plugin

BrowserPaw also ships a Claude Code plugin that bundles the operating skill and the stdio MCP server. With Chrome and the extension already running:

/plugin marketplace add GoldenLoaf24h/browserpaw
/plugin install browserpaw@browserpaw

Choose user, project or local scope in the /plugin panel. The tools appear as mcp__plugin_browserpaw_browserpaw__chrome_*; /browserpaw loads the operating guide. The plugin runs mcp-chrome-stdio from PATH, so install the bridge globally if the shim is missing:

npm install -g ./app/native-server

See INSTALL.md for shell installation, local checkouts and troubleshooting.

🛠️ Tool surface

The canonical chrome_* tools cover task/page ownership, navigation, DOM observation, strict indexed actions, batch and form pipelines, keyboard, uploads, downloads, dialogs, screenshots, visual fallback, network capture, storage, history, bookmarks, performance traces, and bridge health. The live core profile avoids announcing the entire surface to every session.

Use docs/TOOLS.md for generated schemas or call chrome_tool_docs for the exact version in the running Native service. Client prefixes differ: DSH exposes mcp__browserpaw__chrome_*, Claude Code exposes mcp__plugin_browserpaw_browserpaw__chrome_*, and Hermes intentionally exposes a curated browserpaw_* wrapper set.

🧩 Skills, references, and recipes

BrowserPaw keeps reusable knowledge in three separate layers:

The canonical skill is distributed to the ChatGPT/Codex, Claude Code, and DSH plugins unchanged. Hermes uses its own skill template because its public tool surface consists of browserpaw_* wrappers rather than the full chrome_*/MCP namespace. Learned skills are never copied into client plugin directories; every client reads them through the shared Native service.

The references/ files contain durable operational knowledge such as tool selection, action outcomes, visual fallback, task and skill lifecycle, and troubleshooting. They must not contain temporary element references, tab, document, or session IDs, coordinates, credentials, cookies, or user input. Packaged recipes under assets/recipes/ are copied into the Native distribution and remain read-only site guidance.

🏗️ Architecture

AI Client (any MCP-capable agent)
         │  MCP over Stdio (recommended zero-config) or HTTP/SSE on 127.0.0.1:12306
         ▼
Native Messaging Bridge (Fastify + Stdio Host)
         ├── Fast Decision Engine (Jev micro-loop)
         └── Passthrough for extension-executed canonical tools
         │  Chrome Native Messaging
         ▼
Chrome MV3 Extension (Service Worker)
         ├── In-Page Engine (1-based DOM indexing)
         ├── CDP Session Manager
         └── Agent Cursor Overlay

For details, see docs/ARCHITECTURE.md.

📚 Documentation

• Project Map – Navigation hub and reading paths.

• Tool Reference – Schemas for all canonical tools.

• Install & Onboard – Step-by-step setup including Jev key.

• Agent Integration – MCP client configuration.

• Plugin Compatibility – Official package formats and per-client boundaries.

• Architecture – Design and decisions.

• Troubleshooting – Connection and execution issues.

💡 Acknowledgments

• hangwin/mcp-chrome – MV3 extension and Native Messaging bridge foundation.

• browser-use/browser-use – DOM-first indexing principles.

• BrowserOS – DOM diffing and element grep patterns.

• TypeSafe – Jev System One fast-decision models.

📄 Legal & License

This project is licensed under the AGPL-3.0 license (GNU Affero General Public License v3.0 or later).

⚖️ Open Source & SaaS Copyleft (Section 13)

Under the terms of AGPLv3, any modifications, forks, or derivative works—including those hosted remotely as a network service, cloud gateway, or SaaS platform interacting with users over a computer network—must make their complete corresponding source code freely available under the same AGPL-3.0 license.

🛡️ Disclaimer of Warranties & Limitation of Liability

This software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the authors or copyright holders be liable for any claim, damages, account suspensions, data loss, or other liability arising from, out of, or in connection with the software or the use or other dealings in the software.

🌐 Compliance with Third-Party Terms

Users are solely responsible for ensuring that their automated browser workflows comply with all applicable local laws, regulations, and the Terms of Service (ToS) or robots.txt policies of any third-party websites or services accessed.

🏷️ Trademarks & Non-Affiliation

Google Chrome is a trademark of Google LLC. Microsoft Edge is a trademark of Microsoft Corporation. OpenAI and ChatGPT are trademarks of OpenAI, Inc. TypeSafe is a trademark of TypeSafe, Inc. BrowserPaw is an independent open-source project and is not sponsored, endorsed, or affiliated with any of these entities. Third-party software attributions and licenses are documented in NOTICE.

🛡️ Verification & Quality

Development acceptance gates, build/deployment verification, and runtime identity standards are defined in docs/QUALITY.md. Run pnpm verify to execute full static quality and build audits.

Version 4.1.2 is the latest published reliability release. It converges observation scope, explicit interaction outcomes and form-step boundaries so that deterministic tools, batch execution, REPL and Jev return the same facts. Its complete gate, real-browser acceptance, production deployment, Linux/Windows CI and release assets are recorded. The 4.1.2 release also adds explicit delayed-page recovery, fast-observation fail-closed behavior, unified expected-page restriction handling and error-page injection recovery. See the 4.1.2 release record and current development work. The reproduced Native idle protocol failure in 4.1.0 was repaired and verified on an unchanged connection for more than eleven minutes; that bounded evidence is not a guarantee for every long-running workload. The 320-run M7 comparison has stopped; its historical evidence remains available. The planned 95% task success and 20%/30%/50% efficiency thresholds are unproven. Report performance only from matched, versioned runs.

The Jev interaction integration is not yet runtime-qualified. Real Jev 1.14.0 evaluation safely refused two clear targets in an independent Chinese-language holdout, below the acceptance target. Deterministic tools remain the default; do not lower confidence thresholds or infer production accuracy from unit tests. See the development ledger.