browser-automation-cli 0.8.2__tar.gz → 0.8.4__tar.gz

browser_automation_cli-0.8.4/.github/workflows/rust-wheels.yml

@@ -0,0 +1,123 @@
+name: rust-wheels
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+    paths: ["src/**", "Cargo.toml", "Cargo.lock", "pyproject.toml", "install.sh", "tests/**", "benchmarks/performance-test/site/**", ".github/workflows/rust-wheels.yml"]
+  pull_request:
+    paths: ["src/**", "Cargo.toml", "Cargo.lock", "pyproject.toml", "tests/**", ".github/workflows/rust-wheels.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  # Linux validation: the end-to-end suite driven against the Rust daemon + Rust client.
+  test-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: astral-sh/setup-uv@v4
+      - name: Build
+        run: cargo build --release
+      - name: System libs for Chromium (via ephemeral playwright; no project dependency)
+        run: uvx playwright install-deps chromium
+      - name: Native browser install (validates the Rust installer on Linux)
+        run: target/release/browser install
+      - name: End-to-end tests on the Rust daemon
+        env:
+          BROWSER_CLI: ${{ github.workspace }}/target/release/browser
+          BROWSER_DAEMON: ${{ github.workspace }}/target/release/browser-daemon
+          BROWSER_EPHEMERAL: "1"
+        run: python3 -m unittest -v tests/test_cli.py
+      - name: End-to-end tests again with engine=system (the runner's installed Chrome)
+        env:
+          BROWSER_CLI: ${{ github.workspace }}/target/release/browser
+          BROWSER_DAEMON: ${{ github.workspace }}/target/release/browser-daemon
+        run: |
+          target/release/browser engine system
+          BROWSER_EPHEMERAL=1 python3 -m unittest tests/test_cli.py
+          target/release/browser engine auto
+      - name: Daemon log on failure
+        if: failure()
+        run: cat /tmp/test-daemon.log || true
+
+  wheels:
+    needs: test-linux
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, target: x86_64, manylinux: auto }
+          - { os: ubuntu-24.04-arm, target: aarch64, manylinux: auto }  # native: ring/rustls does not cross-compile in the cross-gcc image
+          - { os: macos-14, target: aarch64 }
+          - { os: macos-15-intel, target: x86_64 }
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: ${{ matrix.manylinux || '' }}
+          args: --release --out dist
+      - name: Smoke the client binary (every matrix entry builds natively)
+        run: |
+          set -e
+          pip install dist/*.whl
+          browser --version
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.os }}-${{ matrix.target }}
+          path: dist/*.whl
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Tarballs for install.sh (binaries extracted from each wheel)
+        run: |
+          set -e
+          V="${GITHUB_REF_NAME#v}"
+          for w in dist/*.whl; do
+            case "$w" in *linux*x86_64*) t="linux-x86_64" ;; *linux*aarch64*) t="linux-aarch64" ;; *macosx*arm64*) t="darwin-arm64" ;; *macosx*x86_64*) t="darwin-x86_64" ;; *) continue ;; esac
+            rm -rf tmpw && mkdir tmpw && unzip -q "$w" -d tmpw
+            bin=$(find tmpw -type d -name scripts | head -1)
+            chmod +x "$bin"/browser "$bin"/browser-daemon
+            tar -C "$bin" -czf "dist/browser-cli-$V-$t.tar.gz" browser browser-daemon
+            (cd dist && shasum -a 256 "browser-cli-$V-$t.tar.gz" > "browser-cli-$V-$t.sha256")
+          done
+          rm -rf tmpw; ls -la dist
+      - name: Attach wheels and tarballs to the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release view "${{ github.ref_name }}" --repo "${{ github.repository }}" >/dev/null 2>&1 || gh release create "${{ github.ref_name }}" --repo "${{ github.repository }}" --title "${{ github.ref_name }}" --notes "See the benchmarks/ directory for measurements." --generate-notes
+          gh release upload "${{ github.ref_name }}" dist/* --clobber --repo "${{ github.repository }}"
+      - name: Publish to PyPI (only when the PYPI_API_TOKEN secret is set)
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          if [ -z "$UV_PUBLISH_TOKEN" ]; then echo "PYPI_API_TOKEN not set; skipping PyPI publish"; exit 0; fi
+          pip install uv
+          uv publish dist/browser_automation_cli-*

browser_automation_cli-0.8.4/.gitignore

@@ -0,0 +1,50 @@
+# Build artifacts
+dist/
+build/
+target/
+*.egg-info/
+*.egg
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+
+# Virtual environments
+.venv/
+venv/
+
+.env
+
+# IDE
+.vscode/
+.idea/
+
+# macOS
+.DS_Store
+
+# Release documentation
+RELEASE.md
+
+# Local state
+*.log
+*.tmp
+benchmarks/development-bench/results/calls.log
+benchmarks/development-bench/results/current.json
+
+# busbench (BU Bench V1): browser-use's benchmark keeps its tasks + gold answers secret.
+# Publish the sanitized aggregate (RESULTS.md) + per-task sanitized score.json ONLY.
+# The full per-task record (full.json with answers/ground-truth, traces, streams, screenshots,
+# and the local README index) stays local — never published.
+benchmarks/busbench/results/**
+!benchmarks/busbench/results/*/
+!benchmarks/busbench/results/*/score.json
+benchmarks/busbench/system_prompt_bu_reference.md
+# local rerun/recompute scripts + leaderboard (kept locally, not published).
+# run_suite.sh IS published (the recompute driver); leaderboard may embed per-task results.
+benchmarks/busbench/*.sh
+!benchmarks/busbench/run_suite.sh
+benchmarks/busbench/leaderboard.html
+
+# python caches
+benchmarks/**/__pycache__/

browser_automation_cli-0.8.4/AGENTS.md

@@ -0,0 +1,52 @@
+# Working on this repository
+
+This file is for coding agents (and humans) developing browser-automation-cli itself.
+**If you want to *use* the tool from an agent, read [SKILL.md](SKILL.md) instead**, it is embedded in
+the binary (`browser install skill` installs it into Claude Code / Codex / OpenCode).
+
+The whole project is Rust: one binary (`browser`, with a `daemon` subcommand) plus a `browser-daemon`
+compat shim, driving Chrome over raw CDP via a websocket, no Python, Playwright, or Node at runtime.
+
+## Layout
+
+| path | what it is |
+|---|---|
+| `src/` | the Rust client + daemon (`Cargo.toml` at the repo root) |
+| `src/js.rs` | all injected JavaScript: snapshot (iframe/shadow-DOM aware, `@eN` refs), target resolution (strict mode), settle. Snapshot and targeting share one role/name definition, keep it that way |
+| `pyproject.toml` | maturin packaging (`bindings = "bin"`), builds the two binaries into the `browser-automation-cli` wheel |
+| `install.sh` | installs prebuilt binaries from the GitHub release |
+| `tests/test_cli.py` | 18 end-to-end tests that drive the real daemon through the real CLI (Python is only the test runner + the local test-site fixture; stdlib only) |
+| `benchmarks/performance-test/` | tool benchmark (latency, tokens, idle CPU/RSS) and one-off probes |
+| `benchmarks/development-bench/` | agent benchmark: 17 verifier-judged tasks run by fresh LLM subagents |
+
+## Build and test
+
+```bash
+cargo build --release
+BROWSER_CLI=$PWD/target/release/browser \
+BROWSER_DAEMON=$PWD/target/release/browser-daemon \
+  python3 -m unittest -v tests/test_cli.py
+```
+
+The test suite needs a `python3` on PATH (stdlib only, it's the test runner and serves the local test
+site) and a Chromium for the daemon (`target/release/browser install`). `BROWSER_CLI` / `BROWSER_DAEMON`
+default to `target/release/…` when unset.
+
+CI (`.github/workflows/rust-wheels.yml`) runs the suite on Linux twice (managed build and
+`engine=system`), builds wheels for 4 platforms, and on `v*` tags publishes to PyPI and attaches
+release assets. Chromium system libs come from an ephemeral `uvx playwright install-deps` (no project
+dependency). Lint workflow changes with `actionlint` before pushing.
+
+## Non-negotiables
+
+- **Measure before and after.** Any performance/resource claim goes through `benchmarks/performance-test/run.py`
+  (before → change → after) or the agent benchmark; results belong in the relevant benchmark's README / RESULTS.md. macOS `ps pcpu`
+  is a lifetime average, the harness uses `ps -o time` deltas for a reason.
+- **The test suite is the protocol contract.** Don't change request/response shapes without updating
+  the tests (or documenting a legacy shim, as done for `type {selector, text}`).
+- **Agent benchmark subagents run on Claude Sonnet** (`model: "sonnet"`) unless explicitly comparing
+  models; two attempts per task (pass@2) is the minimum for judging a change.
+- **Docs ship with the binary**: `README.md` becomes the PyPI description (maturin reads it at build)
+  and `SKILL.md` is embedded in the binary, both live at the repo root.
+- **Releases**: bump `Cargo.toml` + `pyproject.toml` + `install.sh` together, tag `v<version>`, and
+  let CI publish. PyPI descriptions are frozen per release.

{browser_automation_cli-0.8.2 → browser_automation_cli-0.8.4}/Cargo.lock

@@ -34,7 +34,7 @@ dependencies = [
 
 [[package]]
 name = "browser-cli"
-version = "0.8.2"
+version = "0.8.4"
 dependencies = [
  "base64",
  "futures-util",

{browser_automation_cli-0.8.2 → browser_automation_cli-0.8.4}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "browser-cli"
-version = "0.8.2"
+version = "0.8.4"
 edition = "2021"
 description = "Browser automation daemon + CLI for coding agents. Persistent sessions, no MCP, no extensions."
 license = "MIT"

browser_automation_cli-0.8.4/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Browser CLI Maintainers
+
+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.

browser_automation_cli-0.8.4/Makefile

@@ -0,0 +1,24 @@
+.PHONY: build install wheel daemon help
+
+help:
+	@echo "Browser CLI (Rust) - Usage"
+	@echo ""
+	@echo "  make build            cargo build --release"
+	@echo "  make install          build + download Chromium"
+	@echo "  make wheel            build the PyPI wheel via maturin"
+	@echo "  make daemon           start the browser daemon (foreground)"
+	@echo "  browser create        create a new session"
+	@echo "  browser list          list sessions"
+	@echo "  browser <id> <cmd>    run a command on a session"
+
+build:
+	@cargo build --release
+
+install: build
+	@./target/release/browser install
+
+wheel:
+	@uvx maturin build --release
+
+daemon:
+	@./target/release/browser daemon

{browser_automation_cli-0.8.2 → browser_automation_cli-0.8.4}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: browser-automation-cli
-Version: 0.8.2
+Version: 0.8.4
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
+License-File: LICENSE.txt
 Summary: Browser automation daemon + CLI for coding agents. Persistent sessions, no MCP, no extensions.
 Keywords: browser,playwright,automation,cli,agent
 License-Expression: MIT
@@ -15,7 +16,7 @@ Project-URL: Repository, https://github.com/jshan9078/browser-automation-cli
 
 # Browser Automation CLI
 
-> **If you are an LLM using this tool, read [SKILL.md](https://github.com/jshan9078/browser-automation-cli/blob/main/SKILL.md)** — or run `browser install skill` to add it to Claude Code / Codex / OpenCode. ([AGENTS.md](AGENTS.md) is for agents developing this repo.)
+> **If you are an LLM using this tool, read [SKILL.md](https://github.com/jshan9078/browser-automation-cli/blob/main/SKILL.md)**: or run `browser install skill` to add it to Claude Code / Codex / OpenCode. ([AGENTS.md](AGENTS.md) is for agents developing this repo.)
 
 A lightweight, self-hosted browser automation tool with a background daemon and CLI client. Enables authenticated web automation, screenshots, compact page snapshots, and page interactions via simple CLI commands. Share the [`SKILL.md`](https://github.com/jshan9078/browser-automation-cli/blob/main/SKILL.md) file with your coding agent harness for seamless integration.
 
@@ -23,13 +24,23 @@ A lightweight, self-hosted browser automation tool with a background daemon and
 
 Coding agents need to interact with authenticated web apps. Existing solutions all have tradeoffs:
 
-* **Chrome DevTools MCP** — requires Node.js, per-agent MCP server configuration, Google telemetry by default, and complex setup for each coding agent
-* **BrowserMCP and similar tools** — require installing Chrome extensions, tie into specific ecosystems, and use MCP which bloats the agent's context window with tool definitions and protocol overhead
-* **Playwright/Puppeteer scripts** — require writing code for every interaction, no persistent auth state
-* **AI browser frameworks** — heavy, opinionated, and framework-locked
+* **Chrome DevTools MCP**: requires Node.js, per-agent MCP server configuration, Google telemetry by default, and complex setup for each coding agent
+* **BrowserMCP and similar tools**: require installing Chrome extensions, tie into specific ecosystems, and use MCP which bloats the agent's context window with tool definitions and protocol overhead
+* **Playwright/Puppeteer scripts**: require writing code for every interaction, no persistent auth state
+* **AI browser frameworks**: heavy, opinionated, and framework-locked
 
 Browser CLI solves this with a persistent daemon that any agent can call via subprocess. No extensions, no MCP config, no SDKs, no ecosystem lock-in. Sessions persist across agent calls (and daemon restarts) so you only log in once.
 
+## Benchmarks
+
+On [BU Bench V1](https://github.com/browser-use/benchmark) (browser-use's 100-task benchmark, `opus-4-7`,
+scored by their `gemini-2.5-flash` judge), Claude Code + browser-automation-cli tops every published
+harness × browser-tool configuration:
+
+![BU Bench V1 results](https://raw.githubusercontent.com/jshan9078/browser-automation-cli/main/docs/busbench-results.png)
+
+Methodology and per-task scores: [`benchmarks/busbench/`](benchmarks/busbench/RESULTS.md).
+
 ## Install
 
 ```bash
@@ -141,7 +152,7 @@ All print JSON (snapshot prints text). Add `-s` / `--snapshot` to any action to
 | :-- | :-- |
 | `navigate <url> [--wait load\|domcontentloaded\|networkidle]` | Returns as soon as the page is usable; never fails on a slow `networkidle` |
 | `snapshot [scope] [--all] [--max N] [--json]` | Visible interactive elements + headings. `--all` adds text blocks, `--json` gives boxes and unique selectors |
-| `click <target> [--double]` | Also `click --at X,Y` to click raw viewport pixels (canvas / vision — no DOM target; screenshot first, pixels map 1:1) |
+| `click <target> [--double]` | Also `click --at X,Y` to click raw viewport pixels (canvas / vision, no DOM target; screenshot first, pixels map 1:1) |
 | `type <target> <text> [--sequential] [--submit]` | `fill()` by default; `--sequential` sends key events (autocomplete); `--submit` presses Enter |
 | `press <key> [target]` | `Enter`, `Tab`, `Control+a`, … |
 | `hover <target>` | |
@@ -155,16 +166,16 @@ All print JSON (snapshot prints text). Add `-s` / `--snapshot` to any action to
 | `back` / `forward` | |
 | `batch` | JSON lines on stdin, run in one round-trip, stop at first failure |
 
-**Targets:** `@e12` (ref from snapshot — preferred) · CSS selector · `text=Create` · `role=button[name=Create]` · `label=Email` · `placeholder=Search` · or flags `--text / --role [--name] / --label / --placeholder`. Ambiguous CSS selectors are refused (strict mode) instead of clicking the first match. For canvas / vision cases with no DOM target, `click --at X,Y` clicks raw viewport pixels (take a `screenshot` first; its pixels map 1:1 to click coordinates).
+**Targets:** `@e12` (ref from snapshot, preferred) · CSS selector · `text=Create` · `role=button[name=Create]` · `label=Email` · `placeholder=Search` · or flags `--text / --role [--name] / --label / --placeholder`. Ambiguous CSS selectors are refused (strict mode) instead of clicking the first match. For canvas / vision cases with no DOM target, `click --at X,Y` clicks raw viewport pixels (take a `screenshot` first; its pixels map 1:1 to click coordinates).
 
 ***
 
 ## Architecture
 
 * **Daemon** (`browser-daemon`): Unix socket server (`~/.browser-daemon/socket`, mode 600) owning a headless Chromium, plus a headed one that exists only while some session is `show`n.
-* **CLI** (`browser`): ~40 ms per call, no Playwright import on the daemon path.
+* **CLI** (`browser`): a native Rust binary driving Chrome over raw CDP, ~2 ms per call, no Python/Node at runtime.
 * **Sessions**: one isolated browser context each. Hidden sessions are **frozen** after 10 s idle (script execution paused, ~3% CPU on animated dashboards; callbacks that fire while frozen are dropped, so `BROWSER_FREEZE_AFTER=0` disables it) and **hibernated** to `~/.browser-daemon/sessions/<id>.json` (cookies + storage + URL) after 10 min idle or on shutdown; they are rehydrated transparently on the next command. Tune with `BROWSER_FREEZE_AFTER` / `BROWSER_HIBERNATE_AFTER` (seconds).
-* **Resource profile** (M4, Cloudflare dashboard parked in a session): 2% CPU / 1.1 GB vs 264% CPU / 2.1 GB for v0.2. See [AGENTBENCH.md](AGENTBENCH.md) for the measurements.
+* **Resource profile** (M4, Cloudflare dashboard parked in a session): 2% CPU / 1.1 GB vs 264% CPU / 2.1 GB for v0.2. See [`benchmarks/`](benchmarks/) for methodology and measurements.
 
 ## Anti-Detection
 
@@ -197,26 +208,28 @@ Errors (exit code 1):
 
 Run `browser install skill` to install [`SKILL.md`](SKILL.md) into Claude Code / Codex / OpenCode, or share the file with any other harness.
 
-## Rust implementation (preview)
+## Implementation
 
-`rust/` contains a Rust client and daemon with the same CLI and socket protocol — no Python, Playwright or
-Node at all: `browser install` downloads the same Chrome-for-Testing build Playwright pins (into the same
-cache, so both implementations share it), and `capture` is native too. Per-call overhead 40 ms → 2 ms,
-daemon RSS −90 MB, frame- and shadow-DOM-aware snapshots. See AGENTBENCH.md. Published to PyPI as
-0.4.0 under the same name (wheels for Linux x86_64/aarch64, macOS arm64/x86_64).
+Written entirely in Rust, one binary (`browser`, with a `daemon` subcommand) plus a `browser-daemon`
+compat shim, driving Chrome over raw CDP via a websocket. No Python, Playwright, or Node at runtime:
+`browser install` downloads the Chrome-for-Testing build directly, and `capture` is native too. ~2 ms
+per call, daemon RSS −90 MB vs the old Python build, frame- and shadow-DOM-aware snapshots. See the
+[`benchmarks/`](benchmarks/) directory for measurements. Since 0.4.0 the PyPI package ships these binaries under the same name
+(wheels for Linux x86_64/aarch64, macOS arm64/x86_64).
 
 ```bash
-cd rust && cargo build --release
+cargo build --release
 ./target/release/browser list          # the daemon auto-starts (`browser daemon` runs it in the foreground)
 ```
 
 ## Development
 
 ```bash
-uv sync
-.venv/bin/python -m unittest -v tests/test_cli.py          # end-to-end tests against scratch/bench/site
-.venv/bin/python scratch/bench/run.py <label>              # benchmark (latency, tokens, idle CPU/RSS)
-.venv/bin/python scratch/bench/compare.py baseline <label>
+cargo build --release
+BROWSER_CLI=$PWD/target/release/browser BROWSER_DAEMON=$PWD/target/release/browser-daemon \
+  python3 -m unittest -v tests/test_cli.py                        # end-to-end tests (needs python3 + a Chromium)
+python3 benchmarks/performance-test/run.py <label>               # benchmark (latency, tokens, idle CPU/RSS)
+python3 benchmarks/performance-test/compare.py baseline <label>
 ```
 
 ## Troubleshooting
@@ -224,29 +237,26 @@ uv sync
 | Symptom | Fix |
 | :-- | :-- |
 | `Command not found: browser` | `export PATH="$HOME/.local/bin:$PATH"` |
-| `Daemon not running` | Auto-start was disabled or failed — `browser daemon &`, check `~/.browser-daemon/daemon.log` |
+| `Daemon not running` | Auto-start was disabled or failed, `browser daemon &`, check `~/.browser-daemon/daemon.log` |
 | Browser doesn't launch | `browser install` |
 | `Session not found` | `browser list` |
 | `ref @eN is unknown or stale` | Page changed; run `snapshot` again |
 | `strict mode violation` | Selector matched several elements; use an `@ref`, `--text`, or a tighter selector |
 | Stale Chromium processes | `browser cleanup` |
 
-### Installing the Rust binaries
+### Installing the binaries
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/jshan9078/browser-automation-cli/main/rust/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/jshan9078/browser-automation-cli/main/install.sh | sh
 ```
 
-or simply `uv tool install browser-automation-cli` (0.4.0+ wheels are the Rust binaries). The script installs
-`browser` and `browser-daemon` into `~/.local/bin` (set `BROWSER_CLI_BIN` to change); other platforms: `cd rust && cargo build --release`.
+or simply `uv tool install browser-automation-cli` (the PyPI wheels are the Rust binaries). The script installs
+`browser` and `browser-daemon` into `~/.local/bin` (set `BROWSER_CLI_BIN` to change); to build from source: `cargo build --release`.
 
-Wheel (same PyPI project name, so download stats carry over): `cd rust && uvx maturin build --release` →
-`uv tool install rust/target/wheels/browser_automation_cli-*.whl`. From 0.4.0 the PyPI package ships
-the Rust binaries; the Python implementation remains in `cli/` and `daemon/` for reference and for
-`python -m daemon.server`.
+Wheel: `uvx maturin build --release` → `uv tool install target/wheels/browser_automation_cli-*.whl`.
 
 CI (`.github/workflows/rust-wheels.yml`) builds wheels for Linux x86_64/aarch64 and macOS arm64/x86_64 on every
-push touching `rust/`, runs the end-to-end suite against the Rust daemon on Linux, attaches wheels to the release
+push touching the Rust sources, runs the end-to-end suite against the Rust daemon on Linux, attaches wheels to the release
 on `v*` tags, and publishes to PyPI when a `PYPI_API_TOKEN` repository secret exists. Windows is not a target: the
 daemon speaks over a Unix socket.
 

{browser_automation_cli-0.8.2 → browser_automation_cli-0.8.4}/README.md

@@ -1,6 +1,6 @@
 # Browser Automation CLI
 
-> **If you are an LLM using this tool, read [SKILL.md](https://github.com/jshan9078/browser-automation-cli/blob/main/SKILL.md)** — or run `browser install skill` to add it to Claude Code / Codex / OpenCode. ([AGENTS.md](AGENTS.md) is for agents developing this repo.)
+> **If you are an LLM using this tool, read [SKILL.md](https://github.com/jshan9078/browser-automation-cli/blob/main/SKILL.md)**: or run `browser install skill` to add it to Claude Code / Codex / OpenCode. ([AGENTS.md](AGENTS.md) is for agents developing this repo.)
 
 A lightweight, self-hosted browser automation tool with a background daemon and CLI client. Enables authenticated web automation, screenshots, compact page snapshots, and page interactions via simple CLI commands. Share the [`SKILL.md`](https://github.com/jshan9078/browser-automation-cli/blob/main/SKILL.md) file with your coding agent harness for seamless integration.
 
@@ -8,13 +8,23 @@ A lightweight, self-hosted browser automation tool with a background daemon and
 
 Coding agents need to interact with authenticated web apps. Existing solutions all have tradeoffs:
 
-* **Chrome DevTools MCP** — requires Node.js, per-agent MCP server configuration, Google telemetry by default, and complex setup for each coding agent
-* **BrowserMCP and similar tools** — require installing Chrome extensions, tie into specific ecosystems, and use MCP which bloats the agent's context window with tool definitions and protocol overhead
-* **Playwright/Puppeteer scripts** — require writing code for every interaction, no persistent auth state
-* **AI browser frameworks** — heavy, opinionated, and framework-locked
+* **Chrome DevTools MCP**: requires Node.js, per-agent MCP server configuration, Google telemetry by default, and complex setup for each coding agent
+* **BrowserMCP and similar tools**: require installing Chrome extensions, tie into specific ecosystems, and use MCP which bloats the agent's context window with tool definitions and protocol overhead
+* **Playwright/Puppeteer scripts**: require writing code for every interaction, no persistent auth state
+* **AI browser frameworks**: heavy, opinionated, and framework-locked
 
 Browser CLI solves this with a persistent daemon that any agent can call via subprocess. No extensions, no MCP config, no SDKs, no ecosystem lock-in. Sessions persist across agent calls (and daemon restarts) so you only log in once.
 
+## Benchmarks
+
+On [BU Bench V1](https://github.com/browser-use/benchmark) (browser-use's 100-task benchmark, `opus-4-7`,
+scored by their `gemini-2.5-flash` judge), Claude Code + browser-automation-cli tops every published
+harness × browser-tool configuration:
+
+![BU Bench V1 results](https://raw.githubusercontent.com/jshan9078/browser-automation-cli/main/docs/busbench-results.png)
+
+Methodology and per-task scores: [`benchmarks/busbench/`](benchmarks/busbench/RESULTS.md).
+
 ## Install
 
 ```bash
@@ -126,7 +136,7 @@ All print JSON (snapshot prints text). Add `-s` / `--snapshot` to any action to
 | :-- | :-- |
 | `navigate <url> [--wait load\|domcontentloaded\|networkidle]` | Returns as soon as the page is usable; never fails on a slow `networkidle` |
 | `snapshot [scope] [--all] [--max N] [--json]` | Visible interactive elements + headings. `--all` adds text blocks, `--json` gives boxes and unique selectors |
-| `click <target> [--double]` | Also `click --at X,Y` to click raw viewport pixels (canvas / vision — no DOM target; screenshot first, pixels map 1:1) |
+| `click <target> [--double]` | Also `click --at X,Y` to click raw viewport pixels (canvas / vision, no DOM target; screenshot first, pixels map 1:1) |
 | `type <target> <text> [--sequential] [--submit]` | `fill()` by default; `--sequential` sends key events (autocomplete); `--submit` presses Enter |
 | `press <key> [target]` | `Enter`, `Tab`, `Control+a`, … |
 | `hover <target>` | |
@@ -140,16 +150,16 @@ All print JSON (snapshot prints text). Add `-s` / `--snapshot` to any action to
 | `back` / `forward` | |
 | `batch` | JSON lines on stdin, run in one round-trip, stop at first failure |
 
-**Targets:** `@e12` (ref from snapshot — preferred) · CSS selector · `text=Create` · `role=button[name=Create]` · `label=Email` · `placeholder=Search` · or flags `--text / --role [--name] / --label / --placeholder`. Ambiguous CSS selectors are refused (strict mode) instead of clicking the first match. For canvas / vision cases with no DOM target, `click --at X,Y` clicks raw viewport pixels (take a `screenshot` first; its pixels map 1:1 to click coordinates).
+**Targets:** `@e12` (ref from snapshot, preferred) · CSS selector · `text=Create` · `role=button[name=Create]` · `label=Email` · `placeholder=Search` · or flags `--text / --role [--name] / --label / --placeholder`. Ambiguous CSS selectors are refused (strict mode) instead of clicking the first match. For canvas / vision cases with no DOM target, `click --at X,Y` clicks raw viewport pixels (take a `screenshot` first; its pixels map 1:1 to click coordinates).
 
 ***
 
 ## Architecture
 
 * **Daemon** (`browser-daemon`): Unix socket server (`~/.browser-daemon/socket`, mode 600) owning a headless Chromium, plus a headed one that exists only while some session is `show`n.
-* **CLI** (`browser`): ~40 ms per call, no Playwright import on the daemon path.
+* **CLI** (`browser`): a native Rust binary driving Chrome over raw CDP, ~2 ms per call, no Python/Node at runtime.
 * **Sessions**: one isolated browser context each. Hidden sessions are **frozen** after 10 s idle (script execution paused, ~3% CPU on animated dashboards; callbacks that fire while frozen are dropped, so `BROWSER_FREEZE_AFTER=0` disables it) and **hibernated** to `~/.browser-daemon/sessions/<id>.json` (cookies + storage + URL) after 10 min idle or on shutdown; they are rehydrated transparently on the next command. Tune with `BROWSER_FREEZE_AFTER` / `BROWSER_HIBERNATE_AFTER` (seconds).
-* **Resource profile** (M4, Cloudflare dashboard parked in a session): 2% CPU / 1.1 GB vs 264% CPU / 2.1 GB for v0.2. See [AGENTBENCH.md](AGENTBENCH.md) for the measurements.
+* **Resource profile** (M4, Cloudflare dashboard parked in a session): 2% CPU / 1.1 GB vs 264% CPU / 2.1 GB for v0.2. See [`benchmarks/`](benchmarks/) for methodology and measurements.
 
 ## Anti-Detection
 
@@ -182,26 +192,28 @@ Errors (exit code 1):
 
 Run `browser install skill` to install [`SKILL.md`](SKILL.md) into Claude Code / Codex / OpenCode, or share the file with any other harness.
 
-## Rust implementation (preview)
+## Implementation
 
-`rust/` contains a Rust client and daemon with the same CLI and socket protocol — no Python, Playwright or
-Node at all: `browser install` downloads the same Chrome-for-Testing build Playwright pins (into the same
-cache, so both implementations share it), and `capture` is native too. Per-call overhead 40 ms → 2 ms,
-daemon RSS −90 MB, frame- and shadow-DOM-aware snapshots. See AGENTBENCH.md. Published to PyPI as
-0.4.0 under the same name (wheels for Linux x86_64/aarch64, macOS arm64/x86_64).
+Written entirely in Rust, one binary (`browser`, with a `daemon` subcommand) plus a `browser-daemon`
+compat shim, driving Chrome over raw CDP via a websocket. No Python, Playwright, or Node at runtime:
+`browser install` downloads the Chrome-for-Testing build directly, and `capture` is native too. ~2 ms
+per call, daemon RSS −90 MB vs the old Python build, frame- and shadow-DOM-aware snapshots. See the
+[`benchmarks/`](benchmarks/) directory for measurements. Since 0.4.0 the PyPI package ships these binaries under the same name
+(wheels for Linux x86_64/aarch64, macOS arm64/x86_64).
 
 ```bash
-cd rust && cargo build --release
+cargo build --release
 ./target/release/browser list          # the daemon auto-starts (`browser daemon` runs it in the foreground)
 ```
 
 ## Development
 
 ```bash
-uv sync
-.venv/bin/python -m unittest -v tests/test_cli.py          # end-to-end tests against scratch/bench/site
-.venv/bin/python scratch/bench/run.py <label>              # benchmark (latency, tokens, idle CPU/RSS)
-.venv/bin/python scratch/bench/compare.py baseline <label>
+cargo build --release
+BROWSER_CLI=$PWD/target/release/browser BROWSER_DAEMON=$PWD/target/release/browser-daemon \
+  python3 -m unittest -v tests/test_cli.py                        # end-to-end tests (needs python3 + a Chromium)
+python3 benchmarks/performance-test/run.py <label>               # benchmark (latency, tokens, idle CPU/RSS)
+python3 benchmarks/performance-test/compare.py baseline <label>
 ```
 
 ## Troubleshooting
@@ -209,28 +221,25 @@ uv sync
 | Symptom | Fix |
 | :-- | :-- |
 | `Command not found: browser` | `export PATH="$HOME/.local/bin:$PATH"` |
-| `Daemon not running` | Auto-start was disabled or failed — `browser daemon &`, check `~/.browser-daemon/daemon.log` |
+| `Daemon not running` | Auto-start was disabled or failed, `browser daemon &`, check `~/.browser-daemon/daemon.log` |
 | Browser doesn't launch | `browser install` |
 | `Session not found` | `browser list` |
 | `ref @eN is unknown or stale` | Page changed; run `snapshot` again |
 | `strict mode violation` | Selector matched several elements; use an `@ref`, `--text`, or a tighter selector |
 | Stale Chromium processes | `browser cleanup` |
 
-### Installing the Rust binaries
+### Installing the binaries
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/jshan9078/browser-automation-cli/main/rust/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/jshan9078/browser-automation-cli/main/install.sh | sh
 ```
 
-or simply `uv tool install browser-automation-cli` (0.4.0+ wheels are the Rust binaries). The script installs
-`browser` and `browser-daemon` into `~/.local/bin` (set `BROWSER_CLI_BIN` to change); other platforms: `cd rust && cargo build --release`.
+or simply `uv tool install browser-automation-cli` (the PyPI wheels are the Rust binaries). The script installs
+`browser` and `browser-daemon` into `~/.local/bin` (set `BROWSER_CLI_BIN` to change); to build from source: `cargo build --release`.
 
-Wheel (same PyPI project name, so download stats carry over): `cd rust && uvx maturin build --release` →
-`uv tool install rust/target/wheels/browser_automation_cli-*.whl`. From 0.4.0 the PyPI package ships
-the Rust binaries; the Python implementation remains in `cli/` and `daemon/` for reference and for
-`python -m daemon.server`.
+Wheel: `uvx maturin build --release` → `uv tool install target/wheels/browser_automation_cli-*.whl`.
 
 CI (`.github/workflows/rust-wheels.yml`) builds wheels for Linux x86_64/aarch64 and macOS arm64/x86_64 on every
-push touching `rust/`, runs the end-to-end suite against the Rust daemon on Linux, attaches wheels to the release
+push touching the Rust sources, runs the end-to-end suite against the Rust daemon on Linux, attaches wheels to the release
 on `v*` tags, and publishes to PyPI when a `PYPI_API_TOKEN` repository secret exists. Windows is not a target: the
 daemon speaks over a Unix socket.