browser-harness v0.1.0B

Immutable. This exact content never changes and is served at /api/v1/blob/6aceae3b9dbd04ee.

---
name: browser-harness
description: "Use when automation needs the user's real Chrome with their sessions, cookies and extensions: \"use my real browser\", \"browser-harness\", \"automate with my Chrome\", \"self-healing browser\". CDP over WebSocket; agents write persistent helper code. Not for headless sandbox runs (use /agent-browser)."
metadata:
  source: "https://github.com/browser-use/browser-harness"
  install_path: "~/Developer/browser-harness"
  version: "0.1.0"
---

# browser-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):**
```bash
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
```bash
browser-harness --doctor
```

## Core Workflow

Always use heredoc invocation:

```bash
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:
```bash
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`