Self-Healing Browser Harness That Lets LLMs Drive Any Real Browser

Browser Harness is a thin, editable CDP (Chrome DevTools Protocol) harness that connects an LLM directly to your real browser. It provides a single WebSocket channel to Chrome with no intermediaries, allowing the agent to write missing helpers during execution and improve the harness with every run. The project is built for tasks where you need complete freedom—no scripted steps, no fixed selectors—just the agent figuring out what to do and how to do it.

Traditional browser automation (Playwright, Puppeteer) relies on pre-written scripts with hardcoded selectors and flows. When an LLM needs to interact with a web page—like uploading a file, filling a complex form, or navigating a multi-step checkout—the script must be updated every time the page changes. Browser Harness solves this by letting the agent write the missing helper on the fly. The harness itself is less than 1,000 lines of code, and the agent can edit its own workspace files (agent_helpers.py and domain skills) to adapt to new scenarios. This makes the system self-healing: the more it runs, the smarter it gets.

The harness's core is a thin CDP wrapper that opens a WebSocket to Chrome's remote debugging endpoint. The agent can call any CDP command directly, but more importantly, it can write and reuse Python helpers in agent_helpers.py and domain-specific skills in agent-workspace/domain-skills/. When the agent encounters a new task—like uploading a file to a certain site—it figures out the selectors and flow, then saves that knowledge as a browser skill. Next time, the skill is already there. The environment variable BH_DOMAIN_SKILLS=1 enables domain skills during execution. Skills are not hand-authored; they are generated by the agent from actual runs, ensuring they reflect what really works in the live browser.

The project is organized into a small Python package (src/browser_harness/) and a user-facing agent workspace. The four core files are: install.md (first-time setup), SKILL.md (daily usage), src/browser_harness/ (the protected core), and the agent workspace located at ${XDG_CONFIG_HOME:-~/.config}/browser-harness/agent-workspace/. The workspace contains agent_helpers.py (helper code the agent edits) and domain-skills/ (reusable browser skills). The browser-harness CLI command attaches to the running Chrome/Chromium CDP endpoint. For isolated automation, you can launch Chrome yourself with --remote-debugging-port and pass BU_CDP_URL, or use a Browser Use cloud browser. The entire project is around 1,000 lines of code across those files.

The recommended way to get started is to paste the following setup prompt into your coding agent (e.g., Claude Code or Codex):

Install or upgrade browser-harness to the latest stable version with uv using Python 3.12, register the skill from `browser-harness skill`, and connect it to my browser. Follow https://github.com/browser-use/browser-harness/blob/main/install.md if setup or connection fails.

The agent will then open chrome://inspect/#remote-debugging and walk you through enabling remote debugging. You need to tick the checkbox and allow the per-attach popup (Chrome 144+). Once connected, the harness is ready. You can test it with a simple one-liner:

./browser-harness <<'PY'
print(page_info())
PY

If you want to use Browser Use Cloud browsers (free tier available), grab an API key from cloud.browser-use.com/new-api-key or let the agent sign up itself via docs.browser-use.com/llms.txt.

Browser Harness shines in scenarios where you need an LLM to perform complex, multi-step browser tasks that are not easily scripted—like scraping data behind login walls, filling out adaptive forms, or automating repetitive workflows on sites that change frequently. It also supports persistent browser sessions, cross-origin iframes, drag-and-drop, file uploads, shadow DOM, and more (see the interaction-skills/ directory). However, it has some limitations: it currently only works with Chrome/Chromium (including headless mode) and requires the remote debugging feature to be enabled. The agent must be capable of writing Python code; if the LLM is weak at code generation, the self-healing mechanism may not work well. Also, because the harness gives the agent full control of the browser, security considerations apply—never run it on untrusted or sensitive pages without proper isolation. The project is MIT licensed and open to contributions, especially domain skills for common sites (LinkedIn, Amazon, etc.).