# Browser Harness

> Give a coding agent your real browser over one CDP websocket

- Category: Agents & Automation / Computer & Browser Use
- Language: Python
- Licence: MIT
- Repository: https://github.com/browser-use/browser-harness
- Website: https://browser-harness.com
- Canonical page: https://ai-tldr.dev/tools/browser-harness/

## In short

Browser Harness connects a large language model directly to a real browser through a single Chrome DevTools Protocol websocket. It sits in the Computer & Browser Use category of the Agents & Automation tools and is open-source, written in Python and licensed MIT. To get started: install the CLI and register the skill.

## Overview

Browser Harness connects a large language model directly to a real browser through a single Chrome DevTools Protocol websocket. Rather than shipping a fixed catalogue of browser actions, it exposes a small Python surface the agent drives, and when a capability it needs is missing the agent writes the helper itself into its own workspace file, so the toolkit grows with each task.

It is designed to be installed as a skill for a coding agent such as Claude Code or Codex: you install the CLI, register `browser-harness skill` as the skill body, and connect it to Chrome's remote-debugging endpoint. Because it drives the browser you are already signed into, it can work on logged-in sites without a separate authentication dance.

The project comes from the Browser Use team and is MIT-licensed. Local Chrome needs no API key; Browser Use Cloud is an optional paid path when you want many browsers in parallel with live previews, proxies, stealth and CAPTCHA solving. Local screenshot-and-trace recording is opt-in and defaults to off, because recordings can capture sensitive page content.

## What it does

- One editable CDP websocket to your real, already-logged-in Chrome — no separate managed browser profile
- Self-extending helper workspace: the agent writes missing helpers into `agent_helpers.py` while the harness source stays protected
- Ships as an agent skill — `browser-harness skill` emits the SKILL.md that teaches the browser workflow
- A `--doctor` command that reports whether Chrome is running, the daemon is alive and the CDP endpoint is reachable
- Opt-in local recordings (screenshots and action traces), disabled by default, with the preference preserved across upgrades
- Optional remote/cloud browsers addressed by name for parallel work

## Getting started

Install the CLI with uv, register it as a skill for your coding agent, then confirm the connection to Chrome. The repo's install.md is written to be pasted into an agent, but the commands work by hand too.

1. Install the CLI and register the skill

   The explicit Python 3.12 selection stops uv from picking an older release. This example registers the skill for Codex; for Claude Code, register a skill named browser-harness with the same body.

```bash
uv tool install --python 3.12 --upgrade --force browser-harness
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness"
browser-harness skill > "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness/SKILL.md"
```

2. Allow remote debugging in Chrome

   Open chrome://inspect/#remote-debugging and tick "Allow remote debugging for this browser instance". This one-time checkbox is deliberately manual — the harness cannot set it for you.

3. Verify the connection

   Pipe a snippet into the CLI. If page_info() prints, the agent can reach your browser.

```bash
browser-harness <<'PY'
print(page_info())
PY
```

4. Set your recording preference

   Recordings save screenshots and action traces locally and may include sensitive page content, so they default to off. Enable them only if you want to ask the agent to replay what it did.

```bash
browser-harness recordings          # show current setting
browser-harness recordings disable  # or: enable
```

5. Diagnose a broken setup

   Reports Chrome, daemon and CDP status, and whether an update is available.

```bash
browser-harness --doctor
```

## When to use it

- Let a coding agent work inside sites you are already logged into, such as pulling your own posts or exports down from an account
- Automate a repetitive web workflow whose steps do not fit a fixed action API, letting the agent write the helper it needs
- Drive browser-based testing or scraping from an existing coding agent instead of maintaining a separate automation script
- Scale a working local flow out to many parallel browsers via Browser Use Cloud once it is proven