Browser Harness ♞

This is the cecli fork of Browser Harness. It is published to PyPI as cecli-browser-harness so cecli can depend on a registry package instead of a git URL. The browser-harness CLI command is unchanged.

Browser Harness lets Claude Code, Codex or Cursor use your real Chrome browser: open pages, click, type, read and download, logged in as you. Paste one prompt into your coding agent to set it up. It talks to Chrome over the DevTools Protocol (CDP), and the agent writes any missing helper as it works, so the harness gets better with each task. Open source, MIT licensed.

Try browser-harness in Browser Use Cloud or paste the setup prompt into your coding agent.

  ● agent: wants to upload a file
  │
  ● agent-workspace/agent_helpers.py → helper missing
  │
  ● agent writes it                         agent_helpers.py
  │                                                       + custom helper
  ✓ file uploaded

You will never use the browser again.

See it work

Task: "Open my X profile, find my latest 20 video posts, and download them."

Setup prompt

Paste into Claude Code or Codex (Cursor: use the MCP config below):

Install or upgrade the `cecli-browser-harness` package (it provides the `browser-harness` command) to the latest stable version with uv using Python 3.12, then 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/cecli-dev/cecli-browser-harness/blob/main/install.md if setup or connection fails.

The agent will open chrome://inspect/#remote-debugging. On first setup, tick the checkbox so the agent can connect to your browser:

How it works

• install.md connects the agent to your browser.
• SKILL.md teaches it the browser workflow.
• src/browser_harness/ stays protected while the agent writes reusable helpers in its local workspace.

Compared with other browser tools

Matched eval by Browser Use on 100 of the 200 public BU Bench V2.1 tasks (bu2-001 to bu2-100; 101-200 not run). Measured 2026-10-14.

• Same agent for every tool: Codex CLI 0.144.6, GPT-6 Luna, medium reasoning, web search off. Same frozen judge.
• Browser Harness was given to the agent as its CLI and SKILL.md, not browser-harness-mcp. Playwright MCP and Chrome DevTools MCP ran as MCP servers with default settings. agent-browser ran as its CLI and skill.
• Every tool drove the same fresh Browser Use cloud browser over CDP. This does not measure each tool's default or local-Chrome mode.
• One run per task. Agent failures were never retried. Runner, browser and judge failures were rerun once (Browser Harness 3 tasks, Playwright MCP 4, Chrome DevTools MCP 6, agent-browser 0).

No tool wins on score: every paired difference against Browser Harness has a 95% CI that includes zero (other tool minus Browser Harness: agent-browser -4.0, CI -10.0 to +1.8; Playwright MCP -0.4, -6.6 to +5.7; Chrome DevTools MCP +0.6, -5.6 to +6.6).

Browser Harness had the lowest median input tokens (2.1M vs 3.3-6.7M) and the lowest median model cost ($0.042 vs $0.056-0.097). Model cost excludes browser, proxy and judge. It was slower than Playwright MCP and Chrome DevTools MCP (median 9.0 vs 8.3 and 8.7 min) and faster than agent-browser (11.2 min). These are medians, with no confidence intervals.

A first agent-browser run was discarded: a setup bug on our side let it launch its own local browser instead of the shared cloud browser. The row shows the corrected rerun.

Measured with Codex only. Claude Code, Cursor, Playwright CLI and Claude in Chrome were not measured. Method and per-task scores: coding-agent-browser-tools.json.

When to use something else

• Playwright (Test, MCP or CLI): isolated, repeatable CI tests of your own app, in a clean browser with no personal logins.
• Chrome DevTools MCP: performance traces and DevTools debugging (network, console, source-mapped stack traces).
• Claude in Chrome: you only use Claude and have a Pro, Max, Team or Enterprise plan.
• Cursor's built-in Browser: the agent doesn't need your logged-in Chrome. It runs in its own per-workspace profile.

OpenAI's Codex labels its browser feature "Browser use" in its settings. It is separate from Browser Use, the company behind this repo.

Scale with Browser Use Cloud

Use your local browser for logged-in, personal work. When you want many browsers in parallel, with live previews, proxies, stealth, CAPTCHA solving, and more, scale with Browser Use Cloud.

MCP server

browser-harness-mcp exposes the browser control helpers as MCP tools over stdio, so any MCP client (Claude Code, Devin, Cursor, etc.) can drive the browser without writing a second CDP layer. See docs/MCP.md for setup and client configuration.

Cursor

Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project. It needs uv.

{
  "mcpServers": {
    "browser-harness": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "cecli-browser-harness[mcp]", "browser-harness-mcp"]
    }
  }
}

Contributing

Bug fixes, documentation improvements, and agent-generated domain skills are welcome. See CONTRIBUTING.md.

The Bitter Lesson of Agent Harnesses · Web Agents That Actually Learn