Browser Harness - Self-Healing Browser Automation
Thin CDP harness (~1K lines, 4 core files) that connects an LLM directly to the user's real Chrome. Screenshot + coordinate-first clicking at the compositor level - works through iframes, shadow DOM, cross-origin without selector hacks. The agent writes missing helpers during execution; the harness improves itself every run. 13.2K stars. Source: GitHub, browser-use/browser-harness, 2026-05-19
Why It Wins
| Concern | browser-harness | Browser Testing Skills | Chrome DevTools MCP |
|---|---|---|---|
| Real browser connection | User's actual Chrome (logins, extensions, cookies) | Lightpanda default (different rendering) | User's browser session |
| Self-healing | Agent writes helpers during execution, persists for next run | No | No |
| Domain skills | Community-contributed per-site playbooks, agent-generated | No (Autobrowse is separate) | No |
| Click mechanism | Compositor-level coordinate clicks (through iframes/shadow/cross-origin) | Ref-based (@e1, @e2) | Manual via eval |
| Primary observation | Screenshots (capture_screenshot → read pixels → act) | Accessibility tree snapshots (~200-400 tokens) | DOM inspection |
| React introspection | No | Yes (react tree, react inspect, react renders, react suspense) | Limited |
| Web Vitals | No | Yes (LCP, CLS, TTFB, FCP, INP + hydration) | No |
| Token efficiency | Higher (screenshots) | Lower (~200-400 tokens per snapshot) | Varies |
| Cloud browsers | Browser Use Cloud (free tier: 3 concurrent, proxies, captcha solving) | agentcore, browserbase, browserless, kernel | No |
Current decision: agent-browser is Kevin's default browser automation surface for agent loops. browser-harness remains a specialist fallback for screenshot-first, self-healing, compositor-click flows against a real Chrome session or Browser Use cloud. Use it deliberately; do not route ordinary browsing, scraping, forms, screenshots, or local UI checks away from Browser Testing Skills by habit. Source: User, 2026-05-19; User request, 2026-07-04
Architecture
Chrome / Browser Use cloud → CDP WS → browser_harness.daemon → IPC → browser_harness.run
- ~1K lines across 4 core files
SKILL.md- day-to-day usage (install as agent skill)agent-workspace/agent_helpers.py- helper code the agent edits at runtimeagent-workspace/domain-skills/- per-site playbooks (community-contributed, agent-generated)
Connection Methods
Way 1 (real profile): chrome://inspect/#remote-debugging checkbox → inherits logins, extensions, cookies. Best for agent helping with tasks in your real browser. Source: install.md
Way 2 (isolated): --remote-debugging-port=9222 --user-data-dir=<custom> → clean profile, no popups. Best for unattended automation. Source: install.md
Cloud: Browser Use API - free tier (3 concurrent browsers, proxies, captcha solving). start_remote_daemon("work"). Source: README
Core Workflow
browser-harness <<'PY'
new_tab("https://example.com")
wait_for_load()
capture_screenshot()
PY
Screenshot → read pixels → click_at_xy(x, y) → screenshot to verify. Compositor-level clicks go through iframes/shadow DOM/cross-origin without selector discovery.
Self-Healing Pattern
When the agent encounters a missing capability during execution, it writes the helper code into agent-workspace/agent_helpers.py. Next run picks it up automatically. The harness gets better every time it's used - aligns with the compounding principle. Source: User + README, 2026-05-19
Domain Skills
Set BH_DOMAIN_SKILLS=1 to enable. goto_url surfaces up to 10 skill filenames for the navigated host. Skills are agent-generated from actual browser sessions, not hand-authored. Community contributes via PR. Source: SKILL.md
Install
git clone https://github.com/browser-use/browser-harness ~/Developer/browser-harness
cd ~/Developer/browser-harness
uv tool install -e .
Register as agent skill via symlink to SKILL.md. Auto-updates: browser-harness --update -y. Health check: browser-harness --doctor.
Timeline
- 2026-07-04 | Demoted from default ad-hoc browser route to specialist fallback after Kevin made agent-browser the default agent browser substrate; keep browser-harness for screenshot-first self-healing real-Chrome flows. Source: User request, 2026-07-04
- 2026-05-19 | Page created. Kevin identified browser-harness as the best overall browser automation tool. 13.2K stars. Added to tool hierarchy at #1 for ad-hoc browsing and visual regression agent loops. Source: User + GitHub, 2026-05-19