Jonathon's AI Wiki

Browser Harness — CDP Browser Control Skill for Claude Code

8 min read

Source: browser-harness.com landing + browser-use/browser-harness on GitHub (README + install.md + SKILL.md) + browser-use.com parent platform Repo: https://github.com/browser-use/browser-harness Stars: 10.7k (captured 2026-05-05) · Forks: 970 Language: Python (100%) · License: MIT Org: browser-use — same team as the video-use Claude skill

browser-use/browser-harness is a thin, self-healing Chrome DevTools Protocol (CDP) wrapper that connects an LLM directly to a real Chrome browser through a single websocket. The agent calls into the harness like any Python module; when it needs a capability the harness doesn’t have, it writes a new helper in agent_helpers.py mid-run. Browser Harness ships both as a CLI (browser-harness -c '<python>') and as a Claude Code / Codex SKILL.md import. ~1,000 LOC across four files. The parent company Browser Use sells Browser Use Box (“Your 24/7 Claude agent”) — a hosted Browser Harness + Claude Code environment accessible from Telegram, web, or SSH.

Key Takeaways

  • One websocket to Chrome, nothing between. Coordinate clicks via Input.dispatchMouseEvent (CDP) — they go through iframes, shadow DOM, and cross-origin frames at the compositor level. Headline differentiator vs Playwright / Puppeteer / Selenium, which drive the DOM by selector and break at iframe/shadow boundaries.
  • Self-healing means the agent writes what’s missing. When a task hits a capability the harness lacks (e.g., a particular file-upload pattern), the agent appends a helper to agent-workspace/agent_helpers.py. The harness improves itself every run; per-machine helpers accrue tribal knowledge of the sites the user actually browses.
  • Two-track install. Paste-into-Claude-Code prompt (Set up https://github.com/browser-use/browser-harness for me. Read install.md and follow the steps...) drives the README’s onboarding. Manual install is git clone && cd && uv tool install -e .. Both register the same browser-harness CLI.
  • Multi-runtime skill registration. Claude Code: @~/Developer/browser-harness/SKILL.md import in ~/.claude/CLAUDE.md. Codex: ln -sf "$PWD/SKILL.md" "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness/SKILL.md". Both surfaces auto-load SKILL.md as a tool reference.
  • Critical SKILL.md rule: “First navigation is new_tab(url), not goto_url(url) — goto runs in the user’s active tab and clobbers their work.” Same shape as the Computer Use discipline of asking before mutating user state.
  • Screenshot-first workflow. “Use capture_screenshot() to understand the current page quickly… after every meaningful action, re-screenshot before assuming it worked.” Visual verification beats DOM-state introspection.
  • Domain skills opt-in (BH_DOMAIN_SKILLS=1). Community-contributed playbooks for specific sites (GitHub, LinkedIn, Amazon at fetch time). PRs are expected to be agent-generated from real task runs — not hand-authored. Contribution model mirrors the broader Skills marketplace.
  • Remote / parallel via start_remote_daemon(). Connects to Browser Use Cloud-hosted browsers for parallel sub-agents or headless server use. Requires BROWSER_USE_API_KEY. Free Browser Use Cloud tier: 3 concurrent browsers + proxies + CAPTCHA solving, no card.
  • Browser Use Box is the hosted-Claude-agent product. Wraps Browser Harness + Claude Code in a 24/7 remote environment, controllable from Telegram, web, or SSH. Marketed as “Your 24/7 Claude agent.”
  • Sister project to video-use. Same org, same self-healing-agent pattern, applied to video editing instead of browsing. Both keep the LLM out of the raw bytes (pixels/frames) and on the structured representation (page_info / transcript packs); both expose visual snapshots only at decision points.

Implementation

Tool/Service: browser-use/browser-harness (MIT)

Setup (paste-into-Claude-Code, the README’s primary path):

Set up https://github.com/browser-use/browser-harness for me.
Read `install.md` and follow the steps to install browser-harness and connect it to my browser.

The agent then opens chrome://inspect/#remote-debugging to enable Chrome’s remote debugging port.

Setup (manual, install.md verbatim):

git clone https://github.com/browser-use/browser-harness
cd browser-harness
uv tool install -e .
command -v browser-harness

Claude Code skill import — add to ~/.claude/CLAUDE.md:

@~/Developer/browser-harness/SKILL.md

(adjust the path to wherever the clone lives)

Codex skill import:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness" && \
ln -sf "$PWD/SKILL.md" "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness/SKILL.md"

Smoke test:

browser-harness -c 'print(page_info())'

Required dependencies: Python (the project ships as Python 100%), Chrome with remote debugging enabled, uv (recommended for the install path).

Optional dependencies: BROWSER_USE_API_KEY only when calling start_remote_daemon() for parallel / hosted browsers.

Cost:

  • Browser Harness itself: free, MIT.
  • Browser Use Cloud (only required for start_remote_daemon()): free tier of 3 concurrent browsers + proxies + CAPTCHA, no card.
  • Browser Use Box: pricing not stated on the public landing pages.

Integration notes:

  • Coordinate-click semantics mean selectors and accessibility trees are secondary — the canonical approach is screenshot → identify visible target → coordinate-click → re-screenshot.
  • page_info() returns a structured representation of the current page; treat it as the cheap “read” path. capture_screenshot() is the expensive “look” path; reserve for ambiguity.
  • Helpers added to agent_helpers.py persist per-machine. They’re agent-readable on every subsequent run, so the harness gets stronger with use.
  • The maintainers explicitly want agent-generated PRs for new domain skills — file a PR after the agent successfully completes a task on a new site, with the agent_helpers.py diff and the domain skill scaffold.

Try It

  • Smoke test on the WEO Marketly site. Clone, install, set the import in ~/.claude/CLAUDE.md, then in Claude Code say “open weomarketly.com in a new tab and capture a screenshot.” The first navigation should be new_tab(weomarketly.com), not goto_url. Confirms the harness sees and obeys the SKILL.md rule.
  • Compare against Computer Use on the same task. Same dental-marketing site, same goal (e.g., navigate to the blog index, screenshot the latest post). Computer Use drives the whole desktop; Browser Harness drives only the browser via CDP. Different tradeoff: Computer Use can switch apps, Browser Harness can run remotely in parallel. The two are complementary, not redundant.
  • Run a parallel sub-agent fleet via start_remote_daemon(). Sign up for the free Browser Use Cloud tier (3 concurrent browsers, no card). Have Claude Code spawn three sub-agents to compare three competitor dental websites in parallel. Tests the remote-daemon path that Browser Use Box productizes.
  • Build a dental-domain skill. After running a task on a real dental practice site, file a PR adding the working agent_helpers.py diff + a domain-skills/dental-practice-management/ skill. Tests the contribution model and seeds reusable site logic for the next OmniPresence / SEO task.
  • Substitute for one Clawdbot scrape leg. Clawdbot — Competitive Intelligence (internal)|Clawdbot (internal — references weomarketly-vault topics)‘s 8-channel competitive intel includes a leg that fetches competitor blog posts. Try Browser Harness as the fetch path on a single channel — coordinate clicks should clear most of the modal/overlay friction Clawdbot’s Playwright path hits. Compare reliability + speed.
  • Wrap as a Cowork capability. Browser Use Box’s pitch is essentially “Cowork in someone else’s datacenter.” If a WEO operator already has a Browser Use Cloud key, they can wire the daemon into a Cowork session and let Cowork drive remote browsers without leaving the Cowork surface.
  • video-use — sister project, same org, same self-healing-agent pattern applied to video editing instead of browsing. Both keep the LLM on the structured representation, not the raw bytes.
  • Computer Use (Desktop + CLI) — Anthropic’s first-party desktop-control skill. Browser Harness is browser-only via CDP, can run remotely in parallel; Computer Use is whole-desktop, runs locally. Pair, don’t choose: Computer Use for native apps + multi-app workflows, Browser Harness for headless / parallel / browser-only tasks.
  • TinyFish — Web Infrastructure APIs for AI Agents — adjacent shape (AI-agent web infrastructure). TinyFish ships a managed Search/Fetch/Browser/Agent platform with 28 anti-bot mechanisms; Browser Harness ships an open-source CDP harness you run yourself. Build-vs-buy tradeoff for agent web access.
  • skills — Canonical Anthropic Skills Repository — Browser Harness’s SKILL.md follows the same Agent Skills shape as the canonical Anthropic skills, importable via @path/to/SKILL.md in ~/.claude/CLAUDE.md.
  • Agent Skills Overview (Official Anthropic Docs) — progressive disclosure rationale that justifies Browser Harness’s helper-on-demand pattern.
  • Claude Code Subagents — start_remote_daemon() is the natural path for parallel sub-agents on browser tasks; Browser Use Cloud’s free 3-concurrent-browser tier is enough to run a fleet locally.
  • Skill Design Patterns — Browser Harness illustrates the agent-edits-its-own-tools pattern (agent_helpers.py), which complements progressive disclosure and self-evaluation patterns documented elsewhere.
  • Tutorial: Getting Started with Cowork — Browser Use Box’s “24/7 Claude agent” positioning is the hosted equivalent of a Cowork session running browser tasks; useful comparison for operators choosing where remote-browser work should live.
  • Clawdbot — Competitive Intelligence (internal)|Clawdbot — Competitive Intelligence (internal) — current internal browser-automation leg uses Playwright; Browser Harness is a candidate replacement on legs where iframe/shadow-DOM friction is the bottleneck.
  • The 2026 Claude Code AIOS Pattern — Browser Use Box fits the “access from anywhere” component (Telegram / web / SSH access to a 24/7 Claude agent) called out in the connections article.

Open Questions

  • Browser Use Box pricing. Public landing copy doesn’t disclose tier pricing or rate limits. Worth pulling before recommending it as a managed alternative to a self-hosted Browser Harness + Claude Code stack.
  • Domain-skill set growth. Three skills at fetch (GitHub / LinkedIn / Amazon). Whether the agent-generated PR contribution model produces broad coverage or stalls is the variable that decides how compelling the harness is for niche sites (dental, healthcare).
  • MCP server availability. Browser Use Box markets itself as “Your 24/7 Claude agent” but no MCP endpoint or Anthropic-side integration was surfaced in the fetched copy. If an MCP server exists, it would be the cleanest way to drop Browser Use Box into a Cowork or Managed Agents workflow.
  • Stealth-browser combination. The harness can deploy against Browser Use’s Stealth Browsers product, but the public docs don’t show how detection-resistant the combination is in practice. Worth a hands-on test on at least one site that’s known to fingerprint headless Chrome.
  • Concurrency limits on start_remote_daemon(). Free tier is 3 concurrent browsers; paid tier ceilings are not stated. Important for any sub-agent fleet sizing decisions.

Graph View

Backlinks