browser-harness: the browser automation framework that lets the agent rewrite its own tools

A thin CDP bridge, a live Chrome session, and editable skills turn browser automation into a self-healing workspace for LLM agents.

10 min read • View on GitHub • More from browser-use

A human hand and a mechanical hand reach toward the same browser window, which is split open like a machine casing. Inside, gears suggest WebSocket, CDP, helpers, and skills, while one cracked gear is being repaired in place by a pen-like cursor. The scene explains the article’s core idea: the browser harness is not fixed, it can be extended while it is being used.
The harness is designed to be repaired mid-task, not abandoned when a new browser quirk appears.
Key Takeaways

Most browser automation tools try to make the web behave. browser-harness does something stranger and more useful: it assumes the web will stay messy, and gives the agent permission to patch the harness while the task is still running.

That changes the failure mode. A missing helper is not a stop sign. It becomes a reason to extend the workspace, add a function, or pull in a more specific skill for the site in front of you.

Why this browser harness is different

The core idea is to make web automation as robust for an LLM as it is for a human. If a button moves, a human can still find it. Standard automation breaks. browser-harness uses LLMs to give that 'human-like' adaptability to automated tasks.

gregory-m, Author/Maintainer · X post by gregory-m on the core idea

The surprise is not that browser-harness automates a browser. It is that the harness itself is editable by the agent. When a flow breaks, the right move is often to teach the system a new helper or skill, then continue.

That makes the project feel less like Selenium with an LLM on top and more like a living operating environment for browser work. The browser is still the browser, but the control layer is no longer frozen.

A close-up desk scene shows index cards spread around a browser window in the background. The cards are labeled with site-specific and interaction skills such as GitHub star, LinkedIn login, iframe, shadow DOM, and network request. A small robotic hand rewrites one card with a pencil, showing how knowledge is captured and improved in place. This explains how the project turns web edge cases into reusable operating knowledge.
Skills are the project’s memory. They turn one-off browser tricks into reusable instructions.

The real browser is the point

The repo does not start from a clean, isolated test browser. It attaches to an existing debugging session, which means the agent can work inside a real Chrome window with real tabs, real cookies, and real history.

That matters more than it sounds. A lot of automation breaks the moment it leaves the lab. browser-harness is built for the opposite condition: the browser you already use, with the state already there.

The loop is simple on purpose: try, fail, patch, continue.

# Conceptual shape of the bridge
ws_url = get_ws_url()
daemon.connect(ws_url)

from helpers import *

# The agent can call raw helpers
click(100, 200)
cdp("Runtime.evaluate", expression="document.title")

# If a helper is missing, add it and keep going

How the harness stays tiny

The architecture is intentionally small. Four core files do most of the work, and the rest of the repo is knowledge that teaches the agent how to use them.

FileRoleWhy it matters
daemon.pyKeeps the long-lived Chrome bridge alivePreserves the connection so short-lived agent runs do not have to rediscover the browser
run.pyExecutes Python from stdinLets the agent send small action blocks without ceremony
helpers.pyExposes the tiny control surfaceProvides raw CDP access and a place to add missing functions
admin.pyHandles control and coordinationKeeps the operational pieces separate from task logic

The point is not minimalism for its own sake. The point is to keep the surface area small enough that an LLM can understand it, manipulate it, and extend it without getting lost in framework layers.


Skills are the real product

The most valuable part of the repo may be the least glamorous: the skills folders. interaction-skills/ captures general web primitives. domain-skills/ captures site-specific tricks that are too brittle to rediscover every time.

LayerWhat it teachesExample value
interaction-skillsReusable browser mechanicsShadow DOM, iframes, and network requests become standard moves
domain-skillsSite-specific behaviorA GitHub star can be handled through the stable form submit path instead of fragile clicking

This is where the project starts to look like shared operational memory. One person discovers a stable way to do something. Another task reuses it. Over time, the harness gets smarter in the places that matter.

Why this beats selector-first automation

DimensionPlaywright / Seleniumbrowser-harness
Control modelSelectors and scripted flowsRaw CDP access plus editable helpers
Failure responseUsually stop and fix the testTreat failure as a cue to patch the harness
Browser stateOften provisioned freshAttaches to a live browser with existing context
Knowledge storageUsually inside test codeSplit between helpers and skills
Best fitDeterministic automationAdaptive browser work for LLM agents

Playwright and Selenium are strong tools. They are also selector-first tools, which means they work best when the world can be specified in advance. browser-harness accepts that browser work often cannot be specified that cleanly.

Healenium comes closer to the repair idea, but the center of gravity is still testing. browser-harness is broader. It is built for agent work, where the browser is not just something to validate. It is the workspace.

Where the friction still lives

The self-healing loop is powerful, but it is not free. It adds latency, and it adds dependency on the model’s ability to write useful helpers under pressure.

BenefitTrade-off
Adaptive recoveryMore model calls and more runtime cost
Live browser stateMore coupling to the user’s current session
Editable helpersRequires the agent to reason about code, not just click paths
Shared skillsNeeds curation so knowledge stays trustworthy

That is not a flaw to hide. It is the real engineering trade. The project is making a bet that flexibility is worth more than the illusion of rigidity.

What this project suggests about browser automation

browser-harness points toward a different category of tooling. Not a static SDK, and not a giant platform, but a living environment where code, memory, protocol access, and task execution sit close together.

If that model keeps working, browser automation stops looking like a brittle collection of scripts. It starts looking like a system that can absorb new browser behavior without resetting the whole stack.