Browser Harness ships almost no browser automation code, and that is the whole point. The project opens one websocket to Chrome over CDP, connects an LLM directly to it, and when a helper the agent needs does not exist yet, the agent writes it mid-task. The README puts the core at roughly a thousand lines across four files. Everything past that, the model fills in as it works.
This inverts how most browser tooling is built. The usual approach anticipates every action ahead of time: click, type, upload, wait, and a large surface of selectors and wrappers to cover the cases. Browser Harness bets the opposite way. It stays thin on purpose and treats missing capability as something the agent resolves during execution rather than something the framework has to ship.
One websocket, nothing between
The connection model is deliberately plain. Plain browser-harness helper calls attach to the running Chrome or Chromium CDP endpoint, so the agent is driving your actual browser with your actual logged-in sessions, not a fresh sandbox. For isolated runs you can launch Chrome yourself with --remote-debugging-port and pass BU_CDP_URL, or point it at a Browser Use cloud browser.
Setup matches that minimalism. You paste a prompt into Claude Code or Codex telling it to install browser-harness with uv on Python 3.12, register the skill, and connect. The agent then opens chrome://inspect/#remote-debugging, you tick the checkbox, and on Chrome 144 and up you click Allow on the per-attach popup. That is the handshake. From there the agent has a direct line to the browser.
The agent writes the missing code
The self-healing loop is the most interesting design choice in the repo. The README sketches it directly: the agent wants to upload a file, the matching helper in agent_helpers.py is missing, so the agent writes the helper, and the upload goes through. That agent_helpers.py file lives in the agent workspace under your config directory and is meant to be edited by the model. The src/browser_harness/ package stays protected as the core.
The claim that follows from this is that the harness improves itself every run. Each time the agent solves something non-obvious, the code it wrote to solve it stays behind. The next task that needs the same move already has the helper. Over time the thin core stays thin while the workspace accumulates exactly the glue your tasks actually required, and nothing you did not.
Skills you are not supposed to write
Domain skills extend the same idea from single helpers to whole site flows. These are reusable, site-specific routines stored in domain-skills/, and you turn them on by setting BH_DOMAIN_SKILLS=1. A skill captures the selectors, flows, and edge cases for a given site so the agent does not rediscover them on every visit. The repo ships examples under folders like github/, linkedin/, and amazon/.
The contribution rule is what stands out. The README says skills are written by the harness, not by you, and asks people not to hand-author them. You run your real task, the agent figures out what works in the live browser, and it files the skill itself. The suggested contribution is to open a PR with the generated domain-skills/<site>/ folder for something you do often, such as LinkedIn outreach, ordering on Amazon, or filing expenses. The reasoning is that agent-generated skills reflect what actually works, while hand-written ones reflect what someone guessed would work.
Where it runs
Local Chrome is the default path, but the project also points at Browser Use Cloud for stealth, sub-agents, or headless deployment. The README describes a free tier with three concurrent browsers, proxies, and captcha solving, and no card required. You can grab an API key, or let the agent sign itself up through the documented setup flow.
Browser Harness is MIT licensed and, per its own framing, argues a specific position about agent design: give the model raw access and a place to write code, and let capability accumulate from real runs instead of being specified in advance. The two posts linked at the bottom, on the bitter lesson of agent harnesses and on web agents that actually learn, make that thesis explicit. Whether the thin core holds up under messier tasks is the open question, but the bet is clearly stated in the code layout itself.
GitHub: https://github.com/browser-use/browser-harness
Curated by Agent Palisade — practical AI for small and mid-sized businesses.
Top comments (0)