browser-harness
Self-healing CDP browser automation connecting LLMs directly to a real Chrome instance via WebSocket. Use when you need full browser freedom with the user's actual sessions, cookies, and extensions —
SKILL.mdskills/browser-harness/SKILL.md
GitHubbrowser-harness
Self-healing CDP automation framework. Connects directly to your running Chrome via a single WebSocket — agents get full browser freedom and write missing helpers during execution.
When to Use (Decision Matrix)
| Need | Use This |
|---|---|
| QA testing / regression / health scores | agent-browser / browse |
| Fast data extraction (no rendering) | Lightpanda |
| Full browser interaction (MCP-native) | Playwright MCP |
| Real Chrome with your sessions/cookies/extensions | browser-harness |
| Agent needs to learn and persist site-specific patterns | browser-harness |
| Local dev server testing | webapp-testing |
Use browser-harness when:
- You need the user's logged-in sessions (Gmail, LinkedIn, internal tools)
- The task requires extensions or profiles that headless can't replicate
- You want the agent to learn and improve across runs (self-healing)
- You need stealth mode / captcha solving via Browser Use Cloud
Do NOT use when:
- You only need DOM extraction (Lightpanda is 9x faster)
- You need structured QA reports with health scores (agent-browser)
- You need MCP-native tool calls without heredocs (Playwright MCP)
Setup
Installed at: ~/Developer/browser-harness (editable clone)
Binary on PATH: browser-harness
Connect to Chrome
Option A — Real profile (your running Chrome):
Navigate to chrome://inspect/#remote-debugging and tick the checkbox. Chrome 144+ shows a per-attach popup — click Allow.
Option B — Isolated profile (no popups):
chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-harness
BU_CDP_URL=http://127.0.0.1:9222 browser-harness <<'PY'
print(page_info())
PY
Diagnostics
browser-harness --doctor
Core Workflow
Always use heredoc invocation:
browser-harness <<'PY'
new_tab("https://example.com")
wait_for_load()
capture_screenshot()
# Interact via compositor-level clicks (works through iframes/shadow DOM)
click_at_xy(x, y)
capture_screenshot() # verify after every action
PY
Key helpers (pre-imported): page_info(), wait_for_load(), new_tab(url), capture_screenshot(), click_at_xy(x, y), js(code), http_get(url), cdp("Method", params), ensure_real_tab(), restart_daemon()
Self-Healing Pattern
When a helper is missing, write it to ~/Developer/browser-harness/agent-workspace/agent_helpers.py. It takes effect immediately on next invocation (editable install).
Domain Skills
Site-specific playbooks in ~/Developer/browser-harness/agent-workspace/domain-skills/{host}/.
Enable with: BH_DOMAIN_SKILLS=1
Also check shared domain knowledge at ~/.claude/skills/browser-domain-skills/{host}/notes.md before navigating to any known host.
Cloud Browsers
Set BROWSER_USE_API_KEY (get from cloud.browser-use.com), then:
browser-harness <<'PY'
start_remote_daemon("work")
new_tab("https://example.com")
PY
Full Reference
For complete API, interaction skills, and advanced usage:
Read ~/Developer/browser-harness/SKILL.md