harness-browser 0.7.8

Agent-first lightweight browser automation — direct CDP, no Playwright, more accurate and more reliable.

Highlights · Overview · Core Technology · Features · Quick Start · Contents

English · 中文

Harness Browser is a lightweight browser-use style tool that makes an agent's browser usage more accurate and reliable. Unlike typical stacks that route every action through Playwright, it launches a real Chromium and talks to the Chrome DevTools Protocol (CDP) directly — removing the intermediate layer so element targeting is driven by stable, live DOM refs and rarely misses.

Harness Browser's design goal: give an agent a browser it can act on with confidence — accurate clicks, low token cost, and persistent logins — through a small, well-shaped set of tools and a matching CLI.

Note: the install-browser command may bootstrap Playwright once purely to download a Chromium binary. Playwright is not a runtime dependency — the agent always drives the browser over CDP.

✨ Highlights

📌 Overview

Most browser automation tools sit on top of Playwright, which adds a layer of abstraction between the model and the page. Harness Browser skips that layer: it starts a Chromium process with a remote-debugging port and speaks CDP itself. Because the element references come straight from the live page, the agent acts on the real nodes — and those refs stay valid through reflows and re-renders. The result is higher action accuracy and lower token usage, with a persistent profile so logins don't expire mid-task.

🧠 Core Technology

🤔 Features

Browser tools

browser_tool(action=...) exposes the following actions:

CDP session

• BrowserSession.create(profile=...) opens a persistent Chromium session.
• Stateless helper: browser_tool(action="navigate", url=..., profile="work").
• Set BROWSER_USE_IDLE_TIMEOUT_MINUTES to stop a local Chrome profile after that many minutes without real CDP activity (0, the default, disables it).
• await session.close(kill=True) or browser_tool(action="close_session", profile="work", kill=True) stops the local Chrome process immediately. Profile data and login state stay on disk.

CLI

Every tool is also a CLI command:

harness-browser install-browser     # fetch a Chromium binary (one-time)
harness-browser navigate "https://example.com" --profile work
harness-browser dom-tree --profile work
harness-browser click --ref inp_1 --profile work
harness-browser type "harness" --ref inp_1 --profile work
harness-browser screenshot --profile work
# session: open / close-session / new-tab / switch-tab / close-tab / list-tabs

Record & replay

Harness Browser can record a real browsing session and replay it:

1. harness-browser record daemon-start — launch the long-lived recording daemon.
2. harness-browser record start — begin capturing the active tab.
3. Browse normally. A small injected script captures clicks, typed text, navigations, and submits, with privacy redaction of sensitive fields.
4. harness-browser record stop — stop capturing.
5. harness-browser record steps <id> — inspect the semantic steps; record skill <id> emits a draft OpenClaw Skill.
6. harness-browser replay run <id> — re-execute as skill-guided agentic execution (the model replays intent, not brittle coordinates/refs).

Use record list / record show <id> / record status / record doctor to manage recordings.

MCP server

harness-browser ships an MCP server, so any MCP-capable agent can drive the browser through the same tool set.

🚀 Quick Start

Prerequisites

• Python 3.11+
• A Chromium / Chrome binary (auto-downloaded by install-browser)

1. Install

pip install harness-browser
harness-browser install-browser    # fetch a Chromium binary once

2. Use as a library

from harness_browser import BrowserSession

async with await BrowserSession.create(profile="default") as session:
    await session.navigate("https://example.com")
    dom = await session.dom_tree()
    await session.click(ref="btn_1")

Or statelessly:

from harness_browser import browser_tool

await browser_tool(action="navigate", url="https://example.com", profile="work")

3. Use as a CLI

harness-browser navigate "https://example.com" --profile work
harness-browser dom-tree --profile work

4. Record a workflow

harness-browser record daemon-start
harness-browser record start
# ... interact with the page ...
harness-browser record stop
harness-browser record skill <recording_id>   # emit an OpenClaw Skill
harness-browser replay run <recording_id>      # replay it

📑 Contents

• Highlights
• Overview
• Core Technology
• Features
• Quick Start
• Reference
  • CLI reference
  • Development
• Project Info
  • Contributing
  • Related projects
  • License

📖 CLI reference

🛠️ Development

Prerequisites: Python 3.11+, uv

make install          # pip install -e ".[dev]"
make all              # lint + typecheck + test

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run make all before submitting
4. Open a Pull Request

🔗 Related projects

📄 License

This project is licensed under the MIT License.