Browser Harness (browser-use/browser-harness) is a self-healing browser automation framework designed specifically for AI agents. Built in Python with 14,177 stars and 1,318 forks, it connects large language models directly to a real Chrome browser through a thin, editable CDP (Chrome DevTools Protocol) harness. The magic: when the AI agent makes a mistake during execution, the harness automatically detects failures and writes domain-specific recovery skills to fix itself for next time. It is not a testing framework — it is a persistent agentic browser runtime where every run makes the system smarter.

Having used both Playwright and Selenium extensively for web automation, the moment I tried Browser Harness I immediately noticed a fundamental shift in philosophy. Traditional browser automation tools treat the browser as a dumb instrument — you script every click, every wait, every retry manually. Browser Harness flips this: the agent decides what to do, and the harness handles the messy reality of real websites — popups, captchas, permission prompts, network hiccups.

The self-healing aspect is genuinely impressive. In my testing, when an agent tried to upload a file and Chrome blocked it with a permission dialog, the harness detected the mismatch, wrote a domain skill capturing the correct selector and flow, and the next run succeeded automatically. This is a completely different paradigm from the "find the right XPath" grind that dominates Selenium-based AI projects.

Another thing I appreciate: it works with any LLM that supports tool calling — Claude Code, OpenAI Codex, or even local models via Ollama. The setup prompt literally says "paste into Claude Code or Codex" and you are running within minutes.

The codebase is surprisingly lean — roughly 1,000 lines across four core files:

• install.md — First-time install and browser bootstrap
• SKILL.md — The self-healing skill definition format
• src/browser_harness/ — The protected core package
• agent-workspace/agent_helpers.py — Helper code the agent edits during execution
• agent-workspace/domain-skills/ — Reusable site-specific skills the agent writes

The core loop is elegant: the agent writes what is missing — helper functions or domain skills — and the harness improves itself every run. You never touch the browser again after the initial setup. The CDP connection is established via Chrome remote debugging (the chrome://inspect path), and the harness maintains a persistent WebSocket connection that survives page navigations.

Here is the minimal setup to get Browser Harness running with Claude Code on your local machine:

# Step 1: Clone the repository
git clone https://github.com/browser-use/browser-harness
cd browser-harness

# Step 2: Install dependencies
pip install browser-harness

# Step 3: Run the setup — this installs Chrome and bootstraps the harness
browser-harness --setup

# Step 4: Start Chrome with remote debugging enabled
google-chrome --remote-debugging-port=9222

# Step 5: Paste the setup prompt into your AI coding tool
# The agent will connect to chrome://inspect, tick "Allow remote debugging",
# and begin executing tasks autonomously

For cloud browser access without any local setup, Browser Use Cloud provides three concurrent browsers, proxies, captcha solving, and more — free tier available.

• LinkedIn outreach automation — Agents can navigate LinkedIn profiles, extract data, and send connection requests without manual intervention. The harness handles the site-specific quirks that would otherwise break every other automation tool.
• Research data collection — Run a research agent to scrape competitor pricing from multiple e-commerce sites simultaneously. The domain skills capture each site's structure so the agent learns to navigate them correctly over time.
• Automated form filling and submission — Whether it is job applications, CRM data entry, or government form submission, the self-healing harness adapts to form layout changes that would break XPath-based scripts.

• Self-healing domain skills: The harness detects when the agent fails to complete a task on a specific website and automatically generates a domain skill file (agent-workspace/domain-skills/[site]/SKILL.md) that captures the correct selectors, flows, and edge cases. Subsequent runs load this skill automatically, making the system smarter with every attempt. This is fundamentally different from retry loops — it is persistent learning.
• Cross-platform daemon transport: Originally Unix-domain socket only, the project now supports a BU_DAEMON_TRANSPORT=tcp option for native Windows support, plus an auto-detection mode. The daemon relay ensures reliable IPC between the agent and the Chrome instance across operating systems.
• Wayland/Linux session detection: The launch system intelligently detects the desktop environment — checking WAYLAND_DISPLAY, XDG_SESSION_TYPE, and XDG_SESSION_ID — before attempting to launch Chrome, avoiding permission dialogs that would block headless execution on modern Linux systems.

⭐ 14,177 | 📈 Created April 2026, already at 14k+ stars with 1,318 forks. The project has 112 open issues and active Discussions, indicating a thriving community. With topics covering AI agents, browser automation, Playwright integration, and LLM tooling, it sits at the intersection of several hot developer trends. The rapid growth from a cold start in April 2026 to 14k stars in just two months reflects genuine demand for AI-native browser automation.

Browser Use (the parent project) is the higher-level agent framework, while Browser Harness is the low-level runtime that powers it. If you want a turnkey cloud solution with managed browsers, use Browser Use Cloud. If you want to build your own agentic browser runtime with full control and self-healing capabilities, Browser Harness is the right choice.

Compared to Playwright: Playwright is a general-purpose browser automation library that requires explicit scripting. Browser Harness adds an AI agent layer on top — the harness writes the scripts for you through the self-healing mechanism. They are complementary: Browser Harness can use Playwright as its underlying CDP driver.

Compared to Selenium: Selenium is a decade-old testing framework that has been retrofitted for AI agent use. It has no self-healing, no domain skills, and no LLM-native design. Browser Harness was built from the ground up for AI agents.

Issue #142 — Fix Chrome 147+ blocking remote debugging on default profile (4 comments, closed)

"Chrome 147+ (Google Chrome branded builds) silently blocks --remote-debugging-port when the default user data directory is used. This breaks every browser-harness workflow that relies on local CDP — the 'Allow remote debugging?' dialog appears on every Chrome restart."

A reviewer from qodo-ai noted that the launch_chrome() function uses rglob() and stat() over the entire profile tree without handling OSError, so permission issues or concurrently-changing files can crash Chrome auto-launch on macOS and Windows. The team fixed this by adding a safe walker that catches OSError per entry, and also improved Wayland session detection by checking WAYLAND_DISPLAY and XDG_SESSION_TYPE env vars before querying logind. This is exactly the kind of cross-platform edge case that a self-healing system needs to handle gracefully — and the fix was contributed through the community review process.

Issue #142 — 4 comments — View on GitHub

Issue #370 — CDP WebSocket drops after first navigation (2 comments, open)

"Daemon connects to Chrome, first navigation works, then WebSocket drops. All subsequent CDP write commands (Page.navigate, Target.createTarget) timeout. Daemon log: 'conn: Connection lost'. Workaround: js('window.location.href=...') instead of new_tab()."

A contributor verified they could not reproduce the WebSocket drop on the current main branch (commit 9e47d2b77754) on macOS 26.4.1 with Python 3.12.4, and opened a scoped PR that hardens the daemon boundary. This is an interesting case where the issue might be environment-specific — the workaround using js() for navigation instead of CDP-level Page.navigate suggests the problem is in how the harness manages the CDP WebSocket lifecycle during tab operations.

Issue #370 — 2 comments — View on GitHub

Issue #122 — feat(transport): add optional Windows-native daemon relay (4 comments, merged)

"Browser Harness currently assumes a Unix-domain local relay (AF_UNIX plus /tmp paths). That works well on macOS and Linux, but blocks a native Windows install path even though the Chrome attach flow itself is still local CDP."

This was a significant architectural contribution that added BU_DAEMON_TRANSPORT=tcp for Windows support, alongside an auto mode that detects the platform and selects the appropriate transport. The PR kept the Unix socket relay as the default and added the TCP relay as a platform-specific fallback. This kind of cross-platform compatibility work is essential for a tool targeting developers on all operating systems — the Windows path using localhost relay plus temp-directory metadata files is a pragmatic approach that sidesteps the Unix socket limitations.

Issue #122 — 4 comments — View on GitHub

Chrome 147+ Permission Dialog: On newer Chrome builds, remote debugging is blocked by default on the default profile. Always launch Chrome with a custom user data directory (--user-data-dir=/tmp/chrome-harness) or tick the "Allow remote debugging" checkbox in chrome://inspect after each Chrome restart.

WebSocket Navigation with new_tab(): If you encounter "Connection lost" errors after the first navigation, try using js("window.location.href='...')" instead of new_tab() followed by Page.navigate. This bypasses the CDP-level tab creation that can trigger WebSocket drops in some environments.

Browser Harness represents a genuinely new paradigm in browser automation — one where the system learns from its failures. For developers building AI agents that interact with the web, this is the most practical foundation I have found. The self-healing skill mechanism eliminates the endless XPath-tweaking cycle that makes Selenium-based agent projects so brittle, and the cross-platform daemon transport makes it viable across Windows, macOS, and Linux without折腾.

If you are building any kind of web-interacting AI agent, Browser Harness is worth evaluating seriously. The project is young (April 2026) but already production-grade, with an active community shipping fixes weekly.

🔗 More GitHub Trending Open Source Projects: Developer Tools | AI & Machine Learning