Browser Harness ♞
Connect an LLM directly to your real browser via a thin CDP harness, giving agents complete freedom for browser tasks with self-healing capabilities.
Evidence shows: The project connects to the browser via CDP, requiring the user to manually enable remote debugging and allow the connection, which reflects a user confirmation mechanism. However, least privilege is not clearly addressed; the code does not explicitly limit the agent's permissions, and dependencies are pinned, posing supply chain risks. Data flow transparency is insufficient; no explanation of how data is processed or transmitted. Sensitive data handling is not mentioned. External effects: the agent can perform arbitrary browser actions, but no rollback mechanism is provided. Source attribution: publisher is unverified, but the codebase has clear copyright notice. Deductions: lack of least privilege design, opaque data flow, no rollback mechanism.
Evidence shows: The project structure is clear, core file naming is consistent, dependencies are pinned, but failure messages are not detailed. Self-consistency is good, but dependency availability is unverified. Deductions: failure messages not detailed, dependency availability unverified.
Evidence shows: The project targets developers, provides multiple usage scenarios (local, cloud), capability boundaries are documented, but trigger precision is insufficient, environment fit is good. Deductions: trigger precision insufficient, environment fit not fully verified.
Evidence shows: Information architecture is clear, installation notes are detailed, naming is stable, examples and FAQ are provided, but known limitations are not explicit, versioning changelog is missing, maintenance responsibility is unclear. Deductions: known limitations not explicit, versioning changelog missing, maintenance responsibility unclear.
Evidence shows: Output usability is good, marginal value is high, but cost-benefit is not fully explained. Deductions: cost-benefit not fully explained.
Evidence shows: Claim traceability is insufficient, cross-source corroboration is insufficient, fact-inference separation is insufficient. Deductions: claim traceability insufficient, cross-source corroboration insufficient, fact-inference separation insufficient.
- Publisher identity is unverified; proceed with caution.
- Dependencies are pinned; monitor supply chain security.
- Agent can perform arbitrary browser actions; ensure user confirmation is effective.
- No rollback mechanism; failed operations may not be recoverable.
What does this agent do, and when should you use it?
Browser Harness is a self-healing harness that enables LLMs to complete any task in a real browser. It consists of a thin, editable CDP (Chrome DevTools Protocol) bridge, allowing the agent to interact with the browser through a single websocket. The architecture is minimal (~1k lines across 4 core files) and includes install documentation, usage skill (SKILL.md), a protected core package, and an agent-editable workspace for helpers and domain-specific skills. The agent writes what's missing during execution, improving itself every run. It supports connecting to a running Chrome/Chromium instance or isolated automation via BU_CDP_URL or Browser Use Cloud browsers. The tool is targeted at users needing complete freedom for complex browser tasks, such as file uploads or site-specific workflows.
The repository provides the browser-harness command-line tool that the agent calls to attach to a running Chrome/Chromium CDP endpoint and perform browser actions. The end-to-end flow: the user pastes a setup prompt into Claude Code or Codex, the agent installs/upgrades the harness, registers the skill, connects to the browser, and executes tasks. During execution, the agent writes any missing helper functions or domain skills into the agent-workspace/ directory (e.g., agent_helpers.py and domain-skills/). Core components include install.md, SKILL.md, src/browser_harness/, and the agent workspace. It supports local browser recordings (disabled by default, preserving user preference on upgrades). The agent connects via chrome://inspect/#remote-debugging and requires an allow popup for Chrome 144+.
- Developers automating complex browser workflows like file uploads or form submissions in a real Chrome instance, with the agent writing missing helper code on the fly.
- Operations personnel using the agent to autonomously perform repetitive site-specific tasks like LinkedIn outreach, ordering on Amazon, or filing expenses, with the agent generating domain skills.
- Testers leveraging isolated automation via BU_CDP_URL or Browser Use Cloud for headless deployment or stealth operations.
- Users of Claude Code or Codex who want a quick setup by pasting the provided prompt, minimizing manual configuration.
- Users needing sub-agents or stealth features by combining with Browser Use Cloud free tier (3 concurrent browsers, proxies, captcha solving).
What are this agent's strengths and limitations?
- Self-healing design: the agent writes missing helpers and domain skills during execution, reducing manual maintenance.
- Complete browser freedom: direct CDP connection to a real browser, not limited by traditional automation frameworks.
- Lightweight architecture: ~1k lines across 4 core files, simplifying maintenance and review.
- Supports isolated automation: for headless or stealth deployments via BU_CDP_URL or Browser Use Cloud.
- Specific environment requirements: needs Chrome/Chromium with remote debugging enabled, and setup depends on Python 3.12 and uv.
- Relies on agent capabilities: primarily designed for advanced coding agents like Claude Code or Codex; manual use may be complicated.
- Security risks: connecting an uncontrolled agent to your real browser could be risky, requiring trust in the agent's actions.
- Limited documentation: installation and connection steps are primarily driven by the setup prompt, lacking a detailed manual guide; requires following install.md.
How do you install or deploy this agent?
Paste the setup prompt into Claude Code or Codex: "Install or upgrade browser-harness to the latest stable version with uv using Python 3.12, register the skill from browser-harness skill, and connect it to my browser. Ask whether I want local browser recordings enabled; default to no and preserve my existing preference on upgrades. Follow https://github.com/browser-use/browser-harness/blob/main/install.md if setup or connection fails." The agent will open chrome://inspect/#remote-debugging, tick the checkbox to allow remote debugging, and click Allow on the per-attach popup. For manual installation, you need Python 3.12 and uv.
How do you use this agent?
After installation, the agent uses the browser-harness command to interact with the browser. For example, it can run Python snippets like browser-harness with print(page_info()) in an interactive session. For development testing, the ./browser-harness launcher runs the current working tree without activating a virtualenv. To use isolated automation, set BU_CDP_URL to a custom CDP endpoint or use Browser Use Cloud browsers. Enable domain skills by setting BH_DOMAIN_SKILLS=1.
How does this agent compare with similar options?
It integrates with Browser Use Cloud browsers, but as a standalone open-source harness, it can connect to local or cloud browsers.