Browser Harness

Browser Harness connects an LLM directly to your real, logged-in browser through an editable CDP websocket. Instead of relying on a fixed set of pre-built browser actions, the agent writes its own helper functions when it encounters a task it can't handle yet, storing them in a local workspace so future tasks reuse that code. It's built for developers who want an AI agent to operate their actual browser session (with existing logins, cookies, and extensions) rather than a fresh, disposable automation instance.

This is for people comfortable running a coding agent (Claude Code, Codex, Cursor, Devin) and who want that agent to drive a real Chrome browser for personal or account-specific tasks: downloading your own files, navigating sites you're logged into, or automating repetitive web workflows tied to your identity.

Key features

• Self-healing helpers: when the agent hits a missing capability, it writes the helper itself in agent_helpers.py, so the harness accumulates functionality over time instead of staying static.
• Direct CDP connection: the agent connects to your browser over a single editable Chrome DevTools Protocol websocket, operating your real session rather than a sandboxed one.
• Protected core, writable workspace: the core library in src/browser_harness/ stays untouched while the agent's generated code lives in a separate local workspace.
• Skill-based setup: a SKILL.md file teaches the agent the browser workflow, and install.md handles connecting it to your browser, both referenced directly by the setup prompt.
• MCP server support: browser-harness-mcp exposes the browser control helpers as MCP tools over stdio, so MCP clients can drive the browser without building a separate CDP integration.
• Cloud scaling path: for parallel, non-personal workloads, Browser Use Cloud offers multiple browsers with live previews, proxies, stealth, and CAPTCHA solving.
• Optional local recordings: setup lets you opt into local browser recordings, defaulting to off, with the preference preserved across upgrades.

Ideal use cases

• Automating tasks tied to a personal or work browser session, like downloading your own social media content, filling out logged-in forms, or scraping data behind authentication.
• Giving a coding agent (Claude Code, Codex, Cursor, Devin) hands-on browser control through MCP without writing a custom CDP integration layer.
• Building up a library of task-specific browser helpers over time, where repeated similar tasks become faster and more reliable as the agent writes and reuses code.
• It's not the right fit for running many browsers in parallel, anonymous or stealth scraping at scale, or CAPTCHA-heavy automation; for those, Browser Use Cloud is the better option.
• Not suited for environments where you can't expose a local CDP debugging endpoint or run a coding agent alongside the browser.

Installation

The documented setup path is a prompt you paste into a coding agent (Claude Code or Codex), which handles installation and connection:

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 installs the package with uv under Python 3.12, registers the skill, and then asks you to open chrome://inspect/#remote-debugging in Chrome. On first setup, check the box there so the agent can connect to your browser over CDP.

If you prefer running it directly rather than through an agent prompt, consult install.md in the repository for the manual connection steps, and docs/MCP.md for configuring browser-harness-mcp with an MCP client.

For larger-scale or parallel browser automation beyond a single local session, Browser Use Cloud is available separately via an API key at cloud.browser-use.com.