---

💡 Background: Why BrowserClaw? (Click to expand)

Traditional browser automation frameworks (Playwright, Puppeteer, browser-use) run in isolated, throwaway sandboxes. They fail to inherit your active logins, cookies, and extensions. Attempting to copy user profile directories on Windows crashes with [WinError 32] exclusive file sharing locks, while --remote-debugging-port triggers intrusive security banners that ruin unattended automation.

BrowserClaw solves this from the inside: an MV3 Chrome extension paired with a local Native Messaging bridge. It runs inside your everyday Chrome — zero login loss, zero file locks, and zero focus-stealing — turning your real browser into a secure, high-speed automation surface for AI agents.

---

⚡ What is BrowserClaw?

BrowserClaw is a hierarchical dual-brain browser agent platform. It pairs a high-performance MCP execution surface (48 tools, running inside your real Chrome) with a local semantic micro-loop — so a fast decision engine handles the high-frequency "perceive → decide → act" steps, while your reasoning LLM stays in charge of macro planning.

The result: agent browser control that is 3–5× faster and 70–80%+ cheaper on tokens, without giving up CDP fidelity, Shadow-DOM penetration, or anti-bot resilience.

• 🧠 Hierarchical Dual-Brain (chrome_act_toward_goal): A semantic micro-loop perceives, decides, and acts locally at ~200–400ms/step with zero intermediate MCP network round-trips. Powered by TypeSafe Jev System One with automatic heuristic fallback and structured escalation to macro planners.
• 🔑 Everyday Session & Auth Continuity: Runs inside your everyday Google Chrome browser, seamlessly inheriting active Google, GitHub, and enterprise SSO logins without file sharing locks or re-authentication friction.
• 🌲 Pruned 1-Based DOM & Compact AX Tree: Strips decorative DOM noise and redundant closing tags, delivering clean numbered accessibility trees that cut prompt token consumption by 85%+ vs raw HTML.
• ⚡ Code-Driven & Pipelined Execution: Chain complex multi-step interactions, form fills, assertions, and data extractions in a single round-trip via chrome_batch_actions or in-page mcp.* script evaluation.
• 🛡️ Industrial DOM & Deep Shadow Piercing: Recursive composed-tree traversal penetrates multi-layered Web Components (e.g. Reddit Shreddit <shreddit-comment> / <faceplate-tracker>), extracts accessible semantics (aria-label, title, inner SVG titles) from icon-only buttons, and supports closed shadow host composed event fallback.
• 🎯 Visual Fallback Drift Compensation: Real-time dynamic scroll delta compensation (alignVisualCoordinate), document-space coordinate scaling for fullpage captures, automatic scroll centering, and scroll-lock guards during click dispatch.
• 🔄 Adaptive Diffing & Targeted Grep: includeDelta: true piggybacks local DOM mutations directly onto click/fill responses, while chrome_grep provides instant sub-100 token regex and text queries across large documents and shadow trees.
• 🖱️ Human-First Coexistence: Smooth 1:1 spring-kinematics virtual cursor, dedicated colored Chrome Tab Groups, optional Window Isolation Mode, and a frosted-glass takeover banner that yields cleanly to humans on 2FA or captchas.
• 🧭 Comprehensive Local Browser Management: Beyond standard page automation, exposes 48 canonical MCP tools to manage active tabs, windows, cookies, storage, browsing history, and bookmarks under your existing credentials.

---

🧠 How the Dual-Brain Works

┌─ Tier 2 · Macro Planner (your reasoning LLM) ──────────┐
│  Task decomposition, long-horizon reasoning,           │
│  free-text generation, exception takeover              │
└───────────────────────────┬────────────────────────────┘
                            │ MCP (low frequency, macro goals)
                            ▼
┌─ Tier 1 · Semantic Micro-Loop (Native Server) ─────────┐
│  chrome_act_toward_goal internal loop:                 │
│  read_dom → Jev / heuristic decision → act → verify    │
│  ~200–400ms per step · zero MCP round-trips            │
└───────────────────────────┬────────────────────────────┘
                            │ Native Messaging
                            ▼
┌─ Tier 0 · Deterministic Primitives (47 tools + 1 loop = 48 tools) ─┐
│  batch_actions / form_pipeline / interact_index / insert_media ... │
│  Chrome MV3 Extension · CDP physical events                        │
└────────────────────────────────────────────────────────────────────┘

Routing rule of thumb:

• Target index known, action sequence fixed → Tier 0 (chrome_batch_actions / chrome_form_pipeline)
• Natural-language micro-goal, target on page but location unknown → Tier 1 (chrome_act_toward_goal)
• Long-horizon task, novel situation, content generation, or Tier 1 escalates → Tier 2 (your LLM drives the other tools)

Setup: set the TYPESAFE_API_KEY environment variable to enable the Jev engine. Without it, chrome_act_toward_goal automatically falls back to the built-in heuristic engine — always functional, gracefully degraded, and self-reporting via the engine field in every response.

Real-world benchmark (real Jev API, T1–T5)

Task	Wall-clock	Jev calls	Tokens (in/out)	Engine
T1 navigate + search	2,062ms	2	1,737 / 52	jev
T2 form submit	586ms	2	1,666 / 48	jev
T3 select option	249ms	1	781 / 24	jev
T4 modal handling	518ms	2	1,654 / 50	jev
T5 multi-step	574ms	2	1,654 / 51	jev

Single-step median ~260–350ms; end-to-end speedup >75% and token reduction >80% vs an LLM-in-the-loop baseline.

---

🚀 Quick Start

Option 1: Let AI Agent Install (Recommended)

Copy and paste this message directly to your AI assistant (Claude Code, Cursor, Windsurf, Codex):

"Set up BrowserClaw for me: https://github.com/GoldenLoaf24h/browserclaw. Read INSTALL.md and follow the steps."

Your agent will configure the backend automatically. Afterwards, download the latest browserclaw-extension-v*.zip asset from Releases (e.g. browserclaw-extension-v2.9.3.zip), unzip it to a persistent local folder, open chrome://extensions (with Developer mode enabled), and drag that folder in.

Option 2: Add via ChatGPT / Codex Plugin Marketplace

In ChatGPT or Codex, open the Plugin Store / Marketplace, click + in the top-right corner to add a new marketplace, and enter:

https://github.com/GoldenLoaf24h/browserclaw

Then click install on BrowserClaw.

Option 3: Install via Hermes Agent

Install directly from terminal into your active Hermes environment:

hermes plugins install GoldenLoaf24h/browserclaw#plugins/browserclaw
hermes plugins enable browserclaw

Option 4: Manual Developer Installation

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

Then load app/chrome-extension/.output/chrome-mv3 into chrome://extensions.

---

🛠️ Complete Tool Catalog (48 MCP Tools)

All 48 schema-validated tools are grouped into 7 logical categories below. Click any category to expand its tool listing. For machine-readable JSON schemas and detailed option flags, consult docs/TOOLS.md.

🧠 0. Autonomous Goal Execution (1 Tool) — New in v2.8

• chrome_act_toward_goal: Autonomous semantic micro-loop that perceives, decides, and acts toward a natural-language goal within a local Native Server loop (~200–400ms/step). Powered by TypeSafe Jev System One with seamless fallback to heuristic scoring when no API key is available or on quota/network degradation. Automatically escalates ambiguous, destructive, or complex actions back to the macro planner with pre-fetched page context and a Top-3 decision probability distribution.

🌐 1. Navigation & Tab Management (7 Tools)

• chrome_navigate: Navigate to any URL, refresh, or travel history ("back" / "forward"). Native background: true opens tabs silently without stealing user focus.
• chrome_switch_tab: Switch the active browser tab or bind session-level tab affinity without disrupting the user.
• chrome_close_tabs: Close tabs by ID array, URL pattern, or safely close active/session tabs (requires confirm: true to protect personal tabs).
• chrome_move_tab: Reposition tabs by index or detach/transfer tabs across separate browser windows.
• get_windows_and_tabs: List all open Chrome windows and tabs with IDs, active state, URLs, and window titles.
• chrome_attach_tab: Explicitly attach the low-level Chrome DevTools Protocol debugger to a specific tab.
• chrome_detach_tab: Explicitly detach the debugger session from a tab.

📄 2. Content Perception & Data Extraction (5 Tools)

• chrome_read_dom: Pruned interactive DOM tree with 1-based numeric indices. Traverses deep open and closed Shadow DOM boundaries, extracting accessible names from Web Components and icon buttons. Reduces prompt token consumption by >85%.
• chrome_grep: Sub-100 token instant regex or text search across elements and text lines with deep Shadow DOM penetration without full DOM dumping.
• chrome_get_markdown: Clean, structured Markdown content extraction (supports includeLinks: true for link graph extraction) optimized for long-form reading and article summarization.
• chrome_inspect_media: Lossless in-memory extraction of raw <img> and <canvas> data, with 200%+ super-sampling crop fallback for noisy captchas.
• chrome_get_dropdown_options: Inspect all selectable options within native or custom <select> dropdown elements.

🖱️ 3. Action Execution & Pipeline (13 Tools)

• chrome_interact_index: Native trusted click, hover, dblclick, or click sequence (points array) by 1-based index; supports includeDelta: true for autonomous DOM diff feedback and visual coordinate drift compensation (alignVisualCoordinate).
• chrome_fill_index: Native trusted text input with automatic value clearing, Enter key submission, and includeDelta: true mutation checking.
• chrome_insert_media: Direct zero-copy injection of images/media into rich-text editors and composers (e.g. ChatGPT, Claude, Twitter/X, Discord) via clipboard/DataTransfer emulation without native file picker dialogs.
• chrome_batch_actions: High-performance multi-step pipeline combining click, fill, press, and wait in a single roundtrip, with built-in assert and extract rules.
• chrome_form_pipeline: Deterministic multi-step wizard/questionnaire form pipeline — zero model calls, fastest and most reliable for standard form flows.
• chrome_smart_scroll: Viewport overflow-aware scrolling with pixel precision and accurate remaining page counts (pages_down / pages_up).
• chrome_keyboard: Dispatch physical keystrokes (Enter, Tab, Esc), combinations (Ctrl+C/V), or targeted text input.
• chrome_upload_file: Intercept file chooser dialogs dynamically or inject absolute local file paths into <input type="file">.
• chrome_handle_dialog: Handle or pre-arm responses for native JavaScript dialogs (alert, confirm, prompt).
• chrome_handle_download: Track, monitor, and manage active native browser file downloads.
• chrome_computer: Anthropic Computer Use-compatible unified interface for mouse and keyboard control. (Legacy compatibility path — prefer chrome_act_toward_goal for new autonomous loops.)
• chrome_request_human_intervention: Softly dim page, display a frosted-glass banner, park the virtual cursor, and yield control to the human for 2FA or slider captchas.
• chrome_undo_last_action: 5-step ring buffer undo engine to roll back recent navigation jumps or form input values.

👁️ 4. Vision, Console & Low-Level CDP (3 Tools)

• chrome_screenshot: Capture viewport or full-page PNGs with optional high-contrast pixel coordinate grid overlays for visual fallback.
• chrome_console: Capture, monitor, and filter page-level JavaScript console logs, warnings, and unhandled runtime exceptions.
• chrome_cdp_execute: Industrial-grade low-level CDP escape hatch with target polymorphic routing and anti-hang auto-detach guards.

📡 5. Network Intercept & Storage (5 Tools)

• chrome_intercept_api: Silently sniff and decode backend API responses matching URL patterns to retrieve structured JSON data directly.
• chrome_network_capture: Start and stop full network traffic recording with status codes, headers, and request/response payloads.
• chrome_network_request: Dispatch native HTTP requests through the browser session, inheriting all active origin cookies and headers.
• chrome_storage: Read, write, or clear browser storage state (localStorage, sessionStorage, and cookies).
• chrome_javascript: Execute custom JavaScript expressions in the page context with automatic single-expression return detection.

🗂️ 6. Tab Groups, Bookmarks & Diagnostics (14 Tools)

• chrome_tab_group_create: Create dedicated colored tab groups with adaptive task titles (default: "Agent").
• chrome_tab_group_update: Dynamically rename, recolor, or toggle the collapsed state of tab groups.
• chrome_tab_group_list: List all active tab groups in the window and their associated tabs.
• chrome_tab_group_ungroup: Remove specific tabs from their parent group.
• chrome_tab_group_close: Close all tabs in a group and purge the group with zero orphan residue.
• chrome_history: Query and filter historical browser visits across customizable time ranges.
• chrome_bookmark_search / add / delete: Search, create, and remove browser bookmarks.
• performance_start_trace / stop_trace / analyze_insight: Record and analyze Core Web Vitals and Chromium performance traces.
• chrome_tool_docs: Dynamic in-session capability discovery and profile activation (activateForSession: true).
• chrome_doctor: Diagnose environment health, check port 12306, Native Messaging Host, and extension bridge connectivity.

---

🏗️ Architecture

AI Client (Cursor / Claude / Codex)
         │  MCP (HTTP / SSE / Stdio) @ 127.0.0.1:12306
         ▼
Native Messaging Bridge (Fastify + Stdio Host)
         ├── Fast Decision Engine (Jev client + heuristic fallback + micro-loop)
         └── Passthrough for 47 deterministic tools + 1 autonomous micro-loop (48 tools total)
         │  Chrome Native Messaging (1MB buffer guard)
         ▼
Chrome MV3 Extension (Service Worker + WXT + Vue 3)
         ├── Inpage DOM Engine (Isolated World, 1-based indexing)
         ├── CDP Session Manager (10-min retention, domain ref-counting)
         └── Agent Cursor (Closed Shadow DOM spring kinematics overlay)

See docs/ARCHITECTURE.md for detailed topology and ADR records (including ADR-023: the dual-brain decision layer).

---

📚 Documentation Map

• Project Map & Index: 🗺️ Master navigation hub, reading paths by role, and code topology.
• Tool Reference: Auto-generated parameter dictionary for all 48 tools.
• Agent Integration Guide: 6 core interaction rules and client configurations.
• Architecture Deep-Dive: Monorepo design, security boundaries, and ADR records.
• Troubleshooting: Instant diagnosis checklist for connection or execution errors.

---

💡 Acknowledgments & Prior Art

BrowserClaw synthesizes architectural wisdom from the open-source community:

• hangwin/mcp-chrome: Foundational MV3 extension + Native Messaging IPC bridge.
• browser-use/browser-use: Token-efficient DOM-first indexing principles.
• browseros-ai/BrowserOS: Autonomous DOM diffing (includeDelta) and element grep (chrome_grep).
• ChatGPT Official Extension: Spring kinematics virtual cursor and tab group lifecycle patterns.
• TypeSafe Jev — and the jev-browser, jev-voice-browser & jev-ultrafast reference implementations: System One fast-decision patterns, speculative fan-out, and semantic-find criteria design.

---

📄 License

GNU Affero General Public License v3.0 (AGPL-3.0). Modifications or SaaS hosted deployments must remain open-source.

---

Disambiguation: BrowserClaw MCP is an independent Chrome extension and Model Context Protocol automation ecosystem, built for AI agents to control everyday user browsers. It is not affiliated with the standalone browserclaw Playwright library on npm.