browser-harness: a self-healing CDP harness that lets an LLM drive your real Chrome

The problem browser-harness solves: an agent that reuses your logged-in browser

Most browser automation starts by launching a clean, disposable browser. That is a poor fit when the work lives behind a login you already hold: a social account, an internal dashboard, a mailbox. Browser Harness takes the opposite route. The README's headline claim is that it connects an LLM directly to your real browser through one editable CDP websocket, and the tagline that follows is blunt: "You will never use the browser again." The intended user is a developer who already has an agent (Claude Code, Codex, Cursor, Devin or any MCP client) and wants that agent to act inside the browser profile they use daily, rather than a fresh one.

The second half of the pitch is about missing helpers. The README's diagram shows an agent that wants to upload a file, finds no helper for it in agent-workspace/agent_helpers.py, writes one, and finishes the upload. The repository backs this up structurally: src/browser_harness/ is described as protected while the agent writes reusable helpers into its local workspace. So the harness is not a fixed API surface you learn once. It is a thin layer plus a growing local file of agent-authored functions.

One CDP websocket, a protected core, and an agent-written helper file

The architecture visible in the repository is deliberately small. Dependencies in pyproject.toml are four packages: cdp-use==1.4.5, fetch-use==0.4.0, pillow==12.3.0 and websockets==15.0.1. The MCP integration is optional, pulled in only through the mcp extra with mcp==2.1.1. There is no bundled browser engine, no driver binary and no page-object framework. The agent speaks Chrome DevTools Protocol over a websocket to the browser you already have open.

Three files carry the workflow. install.md connects the agent to the browser. SKILL.md teaches it the browser workflow. src/browser_harness/ holds the protected core. The README describes the split in one line: install.md connects, SKILL.md teaches, and the source directory stays protected while the agent writes helpers locally. That separation is the design bet. If the agent could rewrite the core, a bad helper could break the harness permanently; keeping writes confined to a workspace file means the worst case is a bad helper you can delete.

The self-healing loop therefore has a narrow meaning here. It does not mean the harness patches its own source. It means the agent fills gaps in its own toolset at runtime, in a file it owns. Whether those helpers are any good is not something the README claims to measure, and no evaluation numbers appear in the documentation.

Installing browser-harness with uv and running a first task

The README does not give a bare pip command. It gives a setup prompt meant to be pasted into a coding agent such as Claude Code or Codex, and it prescribes uv with Python 3.12 and a skill registration step. The prompt below is quoted from the README; the agent performs the install, so you are delegating the exact command line to it.

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. Ask whether I want local browser recordings enabled; default to no and preserve my existing preference on upgrades. Follow https://github.com/browser-use/browser-harness/blob/main/install.md if setup or connection fails.

Two things in that prompt are worth reading carefully. First, the skill is registered by running browser-harness skill, which matches the console script browser-harness = "browser_harness.run:main" declared in pyproject.toml. Second, the agent is told to ask about local browser recordings and to default to no, preserving your existing preference on upgrades. If you would rather not be asked, decide your answer in advance.

During first setup the agent opens chrome://inspect/#remote-debugging, and the README states you must tick the checkbox there so the agent can connect. That is a manual step in the browser, not something the install can do for you. If setup or connection fails, the README points at install.md as the fallback.

The repository also ships a CLI entry point for MCP use. pyproject.toml declares browser-harness-mcp = "browser_harness.mcp_cli:main", and the README says mcp_server.py exposes the browser control helpers as MCP tools over stdio, so any MCP client can drive the browser without writing a second CDP layer. Setup and client configuration are documented in docs/MCP.md, which is the file to read before wiring a client. The optional extra is declared in pyproject.toml as mcp = ["mcp==2.1.1"].

Remote browsers are the one case with a configuration file. .env.example shows a single variable and states it is only needed for remote browsers:

BROWSER_USE_API_KEY=bu_your_key_here

The comment in that file says to copy it to .env, which is auto-loaded. Local use, which the README frames as logged-in personal work, does not need the key.

Where browser-harness breaks down

The clearest limitation is stated by the project itself, not by a critic. The README splits the two workloads explicitly: use your local browser for logged-in, personal work, and scale with Browser Use Cloud when you want many browsers in parallel with live previews, proxies, stealth and CAPTCHA solving. Read that as a boundary. If your job is a thousand concurrent sessions behind rotating proxies, this repository is not the tool; the README directs you to a separate hosted product for it.

A second constraint comes from the self-healing design. Helpers are written by the agent into agent-workspace/agent_helpers.py. Nothing in the documentation describes a review step, a test gate or a schema for those helpers. An agent that writes a subtly wrong helper for a site can keep calling it, and the failure will look like a site problem rather than a code problem. The workspace layout makes cleanup easy, but it does not make the helper correct.

Maturity is the third thing to weigh. pyproject.toml classifies the project as Development Status :: 3 - Alpha, and the version field reads 0.1.13 while the most recent release listed is v0.1.10. The last push to the repository was on 2026-08-26, so the code is recent, but an alpha classifier on a tool that an agent installs and rewrites at runtime is a real caveat. There is also no documented rollback path in the README: if an upgrade or a newly written helper degrades your setup, the documentation does not describe a supported way back.

Browser Harness vs Playwright: a persistent session against a reproducible one

The comparison people search for is browser-harness vs playwright, and the difference is not speed or API style. Playwright's model is a browser it launches and controls: you write a script, the browser starts, the run is reproducible, and the session ends when the script does. Browser Harness inverts that. The browser already exists, it is yours, and it is logged in. The agent attaches to it over CDP and the state persists between tasks.

That inversion decides which tool fits. Playwright is the better choice when you need deterministic runs in CI, a browser you can throw away, or a suite that another engineer can read and rerun. Browser Harness is the better choice when the session itself is the asset: an account you are signed into, a profile with your cookies, a workflow that would be painful to reproduce from scratch. The same property that makes it useful, a real profile with real credentials, is also the reason to think about what the agent is allowed to touch.

The related question of Browser Use vs Browser Harness has a simpler answer. Browser Harness is the local, thin layer over your own browser, distributed under MIT. Browser Use Cloud is the hosted service the README names for parallel browsers, proxies, stealth and CAPTCHA solving. They are positioned as complements, not substitutes.

Licence, upgrade cost and what an upgrade actually touches

The licence is MIT, declared in pyproject.toml as license = "MIT" with license-files = ["LICENSE"]. That is permissive and places few obligations on how you redistribute or embed the code, though the usual caveat applies: read the LICENSE file and your own legal counsel's view, since this article is not legal advice.

The upgrade path is where the design has a cost. The setup prompt asks the agent to install or upgrade to the latest stable version, and it explicitly tells the agent to preserve your existing recording preference across upgrades. That instruction exists because upgrades are expected to be routine and repeated. Each one brings a new version of the protected core in src/browser_harness/ next to a workspace file that an agent wrote and that nobody reviewed. The two evolve on different schedules.

Python version is a hard floor, not a preference: requires-python is ">=3.11" and the setup prompt says 3.12. If your environment is pinned below 3.11, the install fails before anything else matters. The dependency set is small and version-pinned (cdp-use==1.4.5, fetch-use==0.4.0, pillow==12.3.0, websockets==15.0.1), which keeps the blast radius of a dependency bump narrow but also means you are waiting on upstream pins rather than resolving flexibly.

Editorial conclusion

Adopt browser-harness if your automation depends on a browser you are already logged into, and if you are comfortable letting an agent write helper code into agent-workspace/agent_helpers.py while src/browser_harness/ stays untouched. Do not adopt it if you need many parallel browsers, proxies, CAPTCHA handling or stealth: the README points those workloads at Browser Use Cloud instead. Before you rely on it, verify three things yourself: that the chrome://inspect/#remote-debugging checkbox is ticked on first setup, whether you want local browser recordings enabled (the setup prompt defaults to no), and whether your target site's terms permit this kind of scripted session.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes