Metadata-Version: 2.4
Name: browser-harness-extended
Version: 0.5.5
Summary: Extended fork of browser-harness — adds per-user shadow cache (autotrace+replay), auto-codification of skills, bh-policy.toml trust layer, EU-friendly local-only mode, multi-Chromium fan-out, and a community skill registry pipeline. Drop-in compatible with browser-harness v0.3 + much more.
Author-email: Abhishek Chhetri <abhishekchhetri020@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Browser Use
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Abhishekchhetri020/browser-harness
Project-URL: Repository, https://github.com/Abhishekchhetri020/browser-harness
Project-URL: Changelog, https://github.com/Abhishekchhetri020/browser-harness/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Abhishekchhetri020/browser-harness/issues
Project-URL: Skill Registry, https://github.com/Abhishekchhetri020/browser-harness-skills
Project-URL: Upstream, https://github.com/browser-use/browser-harness
Keywords: browser,automation,cdp,agent,llm,playwright,selenium,chromium,skill-registry,auto-codification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cdp-use==1.4.5
Requires-Dist: fetch-use==0.4.0
Requires-Dist: pillow==12.2.0
Requires-Dist: websockets==15.0.1
Dynamic: license-file

<img src="https://raw.githubusercontent.com/browser-use/media/main/browser-harness/banner-ink.svg" alt="Browser Harness" width="100%" />

# Browser Harness ♞

Connect an LLM directly to your real browser with a thin, editable CDP harness. For browser tasks where you need **complete freedom**.

One websocket to Chrome, nothing between. The agent writes what's missing during execution. The harness improves itself every run.

```
  ● 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.**

## Install (v0.5.1+)

This fork is published to PyPI as **`browser-harness-extended`** — the original
`browser-harness` name is reserved on PyPI. The Python import name is unchanged
(`import browser_harness` still works).

```bash
pip install browser-harness-extended
# or via the GitHub tag (no PyPI required):
pip install "git+https://github.com/Abhishekchhetri020/browser-harness@v0.5.1"
```

> **What's new in v0.4.0** — per-user shadow cache (`autotrace` records, `replay_skill`
> deterministically replays at zero LLM cost), auto-codification of recurring flows into
> committable `.py` skills after 3 successful replays, `bh-policy.toml` trust layer with
> per-host glob allowlists, secret-scanned skill registry pipeline (`publish_skill`
> dry-run + `gh`-CLI live), multi-Chromium fan-out (`launch_browser` for
> Brave/Edge/Arc/Chromium variants), and an EU-friendly `BH_LOCAL_ONLY=1` mode that
> asserts no harness-initiated network egress. Full notes in
> [CHANGELOG.md](CHANGELOG.md). Public data-flow contract in
> [docs/data-flow.md](docs/data-flow.md). Trust-layer schema in
> [bh-policy.toml.example](bh-policy.toml.example).

## Setup prompt

Paste into Claude Code or Codex:

```text
Set up https://github.com/browser-use/browser-harness for me.

Read `install.md` and follow the steps to install browser-harness and connect it to my browser.
```

The agent will open `chrome://inspect/#remote-debugging`. Tick the checkbox so the agent can connect to your browser:

<img src="docs/setup-remote-debugging.png" alt="Remote debugging setup" width="520" style="border-radius: 12px;" />

Click Allow when the per-attach popup appears (Chrome 144+):

<img src="docs/allow-remote-debugging.png" alt="Allow remote debugging popup" width="520" style="border-radius: 12px;" />

See [agent-workspace/domain-skills/](agent-workspace/domain-skills/) for example tasks.

## Free Browser Use Cloud browsers

Stealth, sub-agents, or headless deployment.<br>
**Browser Use Cloud free tier: 3 concurrent browsers, proxies, captcha solving, and more. No card required.**

- Grab a key at [cloud.browser-use.com/new-api-key](https://cloud.browser-use.com/new-api-key)
- Or let the agent sign up itself via [docs.browser-use.com/llms.txt](https://docs.browser-use.com/llms.txt) (setup flow + challenge context included).

## Architecture (v0.4.0 — ~3.5k lines across the core package)

| File | Purpose |
|---|---|
| `src/browser_harness/helpers.py` | Primitive surface auto-imported into `-c` scripts |
| `src/browser_harness/daemon.py` | Long-lived CDP holder + 500-event ring buffer, one per `BU_NAME` |
| `src/browser_harness/admin.py` | Daemon lifecycle, doctor, Browser-Use Cloud session admin |
| `src/browser_harness/snapshot.py` | AX-tree snapshot → `r1`/`r2`/... refs |
| `src/browser_harness/observation.py` | Network + console event drain |
| `src/browser_harness/_audit.py` | NDJSON audit log at `~/.browser-harness/audit.log` |
| `src/browser_harness/_trace.py` | Per-user shadow cache: `autotrace`, `replay_skill`, `list_traces` |
| `src/browser_harness/_codify.py` | Auto-promote N-times-replayed traces → committable `.py` skills |
| `src/browser_harness/_policy.py` | `bh-policy.toml` trust layer; per-host glob allowlists |
| `src/browser_harness/_skills.py` | Skill registry: list / validate / package / publish |
| `src/browser_harness/_browsers.py` | Multi-Chromium detect / `find_free_port` / `launch_browser` |
| `src/browser_harness/_egress.py` | `BH_LOCAL_ONLY` egress gate (EU-friendly mode) |
| `src/browser_harness/mcp_server.py` | MCP tool surface for clients that prefer JSON-RPC over `-c` |
| `src/browser_harness/run.py` | The `browser-harness` CLI |
| `src/browser_harness/_ipc.py` | Token-authed unix socket / TCP loopback |
| `agent-workspace/agent_helpers.py` | Helper code the agent edits |
| `agent-workspace/domain-skills/<host>/` | Per-host skill folders (markdown + auto-codified .py) |
| `bh-policy.toml.example` | Trust-layer schema you can copy and edit |
| `docs/data-flow.md` | Public data-flow contract — what the harness reads, where it goes |
| `docs/registry-template/` | Drop-in template for standing up a community skill registry repo |

179 unit tests. MIT (inherited from upstream `browser-use/browser-harness`).

## Contributing

PRs and improvements welcome. The best way to help: **contribute a new domain skill** under [agent-workspace/domain-skills/](agent-workspace/domain-skills/) for a site or task you use often (LinkedIn outreach, ordering on Amazon, filing expenses, etc.). Each skill teaches the agent the selectors, flows, and edge cases it would otherwise have to rediscover.

- **Skills are written by the harness, not by you.** Just run your task with the agent — when it figures something non-obvious out, it files the skill itself (see [SKILL.md](SKILL.md)). Please don't hand-author skill files; agent-generated ones reflect what actually works in the browser.
- Open a PR with the generated `agent-workspace/domain-skills/<site>/` folder — small and focused is great.
- Bug fixes, docs tweaks, and helper improvements are equally welcome.
- Browse existing skills (`github/`, `linkedin/`, `amazon/`, ...) to see the shape.

If you're not sure where to start, open an issue and we'll point you somewhere useful.

## Domain skills

Set `BH_DOMAIN_SKILLS=1` to enable [agent-workspace/domain-skills/](agent-workspace/domain-skills/) — community-contributed per-site playbooks `goto_url` surfaces by domain. Contribute via PR.

---

[The Bitter Lesson of Agent Harnesses](https://browser-use.com/posts/bitter-lesson-agent-harnesses) · [Web Agents That Actually Learn](https://browser-use.com/posts/web-agents-that-actually-learn)
