BrowserClaw

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 high-performance Model Context Protocol (MCP) platform that gives AI agents complete, authenticated control over your active Chrome browser:

• 🍪 100% Session & Auth Reuse: Keeps your active Google, GitHub, and enterprise SSO sessions. No re-logging in.

• 🎯 Dual-Engine Precision: 1-based pruned DOM tree (token savings >85%) with 1:1 CSS viewport coordinate visual fallback.

• 🌲 AX Compact Semantic Tree (format: "compact"): Accessibility-tree-inspired representation without verbose closing tags, slashing token usage by 60%~75%.

• 🔗 Code-Driven Chained Execution (mcp.*): Run multi-step interactions (mcp.click, mcp.fill, mcp.waitFor, mcp.extract) in a single chrome_javascript call, reducing 4~6 roundtrips to 1.

• 🛡️ Shadow DOM Penetration & Self-Healing Interception: Deep composed-tree hit testing across closed shadow roots with actionable dialog names returned on obstruction.

• 🎯 Optimal Action Point & Click Probe Fallback: Viewport-weighted visible coordinates with automatic synthetic DOM fallback if Chromium throttles background CDP events.

• 📡 4-Tier Layered Scraping Protocol: Seamless escalation from zero-token direct API fetch (chrome_network_request) to silent response sniffing, compact DOM, and visual fallback.

• ⚡ Autonomous DOM Diffing (includeDelta): Single-step click/fill responses include local DOM mutations, eliminating 50% of roundtrips.

• 🔍 Targeted Grep (chrome_grep): Sub-100 token instant element and text search across large documents.

• 🖱️ Human-Grade Aesthetics: 1:1 spring-kinematics virtual cursor overlay and dedicated tab groups lifecycle management.

• 🛡️ Zero-Jitter Session Retention: 10-minute session-aware CDP retention eliminates infobar dropping and viewport accordion shifts.

• 🌐 Manage Everything in Your Real Browser: Unlike conventional automation tools confined to throwaway headless bubbles, BrowserClaw gives your agent full, authenticated control to manage everything in your everyday local browser — active tabs, windows, cookies, browsing history, and bookmarks.

Related MCP server: MCP Chrome Bridge

🚀 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 browserclaw-extension-latest.zip, open chrome://extensions (with Developer mode enabled), and drag the unpacked 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: Manual 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.

⚖️ How BrowserClaw Compares

Every tool in the browser automation ecosystem has distinct architectural tradeoffs and sweet spots. Here is an objective comparison across the dimensions developers and users care about most:

🧭 Choosing the Right Tool for Your Stack

• Choose browser-use if you want a complete, standalone Python agent that runs its own autonomous loop from the terminal.

• Choose Playwright MCP if you need an official Microsoft tool to run cross-browser test suites across Firefox, WebKit, and Chromium in CI/CD.

• Choose Stagehand if you need to scale to thousands of ephemeral cloud browsers without managing local desktop infrastructure.

• Choose BrowserClaw if you want your AI coding assistants (Claude Code, Cursor, Windsurf, Codex) to control the Chrome you actually use every day — inheriting all your active logins, slashing token costs by 85%+, and enjoying human-grade cursor aesthetics with graceful 2FA takeover.

🛠️ Complete Tool Catalog (52 MCP Tools)

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

• 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.

• chrome_read_dom: Pruned interactive DOM tree with 1-based numeric indices. Reduces prompt token consumption by >85%.

• chrome_grep: Sub-100 token instant regex or text search across elements and text lines without full DOM dumping.

• chrome_get_markdown: Clean, structured Markdown content 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_web_content: Event-driven page content extraction with complete status waiting.

• chrome_get_links: Extract all hyperlinks, URLs, and associated anchor texts from the active page.

• chrome_get_dropdown_options: Inspect all selectable options within native or custom <select> dropdown elements.

• chrome_interact_index: Native trusted click, hover, or dblclick by 1-based index; supports includeDelta: true for autonomous DOM diff feedback.

• chrome_fill_index: Native trusted text input with automatic value clearing and includeDelta: true mutation checking.

• 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_smart_scroll: Viewport overflow-aware scrolling that returns accurate remaining page counts (pages_down / pages_up).

• chrome_scroll: Precise pixel-level and directional scroll control across the document or target scrollable containers.

• chrome_scroll_to_text: Automatically search for target text in the page and smoothly scroll it to the center of the viewport.

• 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_burst_interact: Low-latency burst click sequence designed for rapid successive triggers.

• chrome_computer: Anthropic Computer Use-compatible unified interface for mouse and keyboard control.

• chrome_cdp_execute: Industrial-grade low-level CDP escape hatch with target polymorphic routing and anti-hang auto-detach guards.

• 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.

• chrome_screenshot: Capture viewport or full-page PNGs with optional high-contrast pixel coordinate grid overlays for visual fallback.

• chrome_get_mouse_position: Query the real-time physical coordinates and position of the virtual cursor in the viewport.

• chrome_console: Capture, monitor, and filter page-level JavaScript console logs, warnings, and unhandled runtime exceptions.

• 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.

• chrome_tool_docs: Dynamic in-session capability discovery and profile activation (activateForSession: true).

• 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.

🏗️ Architecture

AI Client (Cursor / Claude / Codex)
         │  MCP (HTTP / SSE / Stdio) @ 127.0.0.1:12306
         ▼
Native Messaging Bridge (Fastify + Stdio Host)
         │  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 sequence flows.

📚 Documentation Map

• Project Map & Index: 🗺️ Master navigation hub, reading paths by role, and code topology.

• Tool Reference: Auto-generated parameter dictionary for all 52 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.

📄 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.