Metadata-Version: 2.4
Name: harness-browser
Version: 0.7.3
Summary: AI-friendly browser automation via CDP with profile-based login persistence
Project-URL: Homepage, https://github.com/orcakit/harness-browser
Project-URL: Repository, https://github.com/orcakit/harness-browser
Project-URL: Issues, https://github.com/orcakit/harness-browser/issues
Author: orcakit
License: MIT
License-File: LICENSE
Keywords: ai,automation,browser,cdp,devtools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.5; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/images/banner.jpeg" alt="Harness Browser Banner" width="600" />
</p>

<p align="center">
  <strong>Agent-first lightweight browser automation — direct CDP, no Playwright, more accurate and more reliable.</strong>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white" /></a>
  <a href="https://github.com/orcakit/harness-browser/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green" /></a>
  <a href="https://pypi.org/project/harness-browser/"><img src="https://img.shields.io/pypi/v/harness-browser" alt="PyPI" /></a>
  <a href="https://github.com/astral-sh/ruff"><img alt="Code Style: Ruff" src="https://img.shields.io/badge/code%20style-ruff-000000?logo=ruff&logoColor=white" /></a>
  <a href="https://github.com/orcakit/harness-browser"><img alt="GitHub stars" src="https://img.shields.io/github/stars/orcakit/harness-browser?style=social" /></a>
</p>

<p align="center">
  <a href="#-highlights">Highlights</a> ·
  <a href="#-overview">Overview</a> ·
  <a href="#-core-technology">Core Technology</a> ·
  <a href="#-features">Features</a> ·
  <a href="#-quick-start">Quick Start</a> ·
  <a href="#-contents">Contents</a>
</p>

<p align="center">
  <b>English</b> · <a href="README_CN.md">中文</a>
</p>

---

**Harness Browser** is a lightweight [browser-use](https://github.com/browser-use/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

| | Feature | Description |
|---|---------|-------------|
| ⚡ | **Direct CDP** | Connects straight to Chrome via CDP — no Playwright / intermediate layer |
| 🎯 | **Ref-based targeting** | Stable element refs survive layout reflows, so clicks land where intended |
| 🪶 | **Lightweight DOM** | Token-efficient multi-level DOM keeps prompts small |
| 🔐 | **Auth persistence** | Profile-based logins persist across sessions — no repeated sign-in |
| 🛠️ | **Agent tools** | One stateless `browser_tool` with ~20 actions |
| 💻 | **CLI** | Every action available as a first-class command |
| 🎬 | **Record & replay** | Capture a workflow, then replay it as skill-guided agentic execution |
| 🤖 | **MCP server** | Expose the browser to any MCP-capable agent |

## 📌 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

| Layer | Technology |
|-------|-----------|
| **Language** | Python 3.11+ |
| **Transport** | CDP over `websockets` (hand-rolled async client) |
| **Launcher** | `subprocess` Chromium with `--remote-debugging-port` |
| **DOM** | Multi-level builder + stable `ref` system |
| **Tools** | Stateless `browser_tool` action set |
| **Recording** | Injected JS recorder + semantic collapse + skill generator |
| **Interfaces** | CLI + MCP server |
| **Build / quality** | hatchling · ruff · mypy · pytest |

## 🤔 Features

### Browser tools

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

| Action | Description | Action | Description |
|--------|-------------|--------|-------------|
| `navigate` | Open a URL | `select` | Pick a `<select>` option |
| `dom_tree` | Dump the multi-level DOM | `scroll` | Scroll the viewport |
| `screenshot` | Capture a screenshot | `hover` | Hover an element |
| `click` | Click by ref | `eval_js` | Run JavaScript |
| `type` | Type text by ref | `go_back` / `go_forward` | History nav |
| `fill` | Fill a field by ref | `reload` | Reload the page |
| `press` | Press a key | `new_tab` / `close_tab` | Tab control |
| `wait` | Wait for a condition | `switch_tab` / `list_tabs` | Tab management |
| | | `close_session` | End the session |

### CDP session
- `BrowserSession.create(profile=...)` opens a persistent Chromium session.
- Stateless helper: `browser_tool(action="navigate", url=..., profile="work")`.

### CLI
Every tool is also a CLI command:

```bash
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

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

### 2. Use as a library

```python
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:

```python
from harness_browser import browser_tool

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

### 3. Use as a CLI

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

### 4. Record a workflow

```bash
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](#-highlights)
- [Overview](#-overview)
- [Core Technology](#-core-technology)
- [Features](#-features)
- [Quick Start](#-quick-start)
- **Reference**
  - [CLI reference](#-cli-reference)
  - [Development](#-development)
- **Project Info**
  - [Contributing](#-contributing)
  - [Related projects](#-related-projects)
  - [License](#-license)

## 📖 CLI reference

| Command | Description |
|---------|-------------|
| `install-browser` | Download a Chromium binary (one-time bootstrap) |
| `navigate` / `open` | Open a URL |
| `dom-tree` | Print the multi-level DOM |
| `screenshot` | Capture a screenshot |
| `click` / `type` / `fill` / `press` | Interact by ref |
| `wait` / `select` / `scroll` / `hover` | Page control |
| `eval-js` | Run JavaScript |
| `go-back` / `go-forward` / `reload` | History / reload |
| `new-tab` / `switch-tab` / `close-tab` / `list-tabs` | Tab management |
| `close-session` | End the session |
| `record ...` | `doctor`, `daemon-start`, `daemon-stop`, `status`, `start`, `stop`, `list`, `show`, `steps`, `skill` |
| `replay run <id>` | Replay a recorded workflow |

## 🛠️ Development

**Prerequisites:** Python 3.11+, [uv](https://docs.astral.sh/uv/)

```bash
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

| Project | Description |
|---------|-------------|
| [harness-agent](https://github.com/orcakit/harness-agent) | Agent runtime that drives the browser tools |
| [harness-memory](https://github.com/orcakit/harness-memory) | Memory system for browser-backed agents |
| [harness-gateway](https://github.com/orcakit/harness-gateway) | Multi-platform IM channel bridge |
| [Octop](https://github.com/orcakit/orca) | The self-hosted assistant that composes the Harness stack |

## 📄 License

This project is licensed under the [MIT License](LICENSE).
