browser-automation-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{browser_automation_cli-0.2.1 → browser_automation_cli-0.3.0}/.gitignore

@@ -26,3 +26,5 @@ RELEASE.md
 # Local state
 *.log
 *.tmp
+scratch/agentbench/results/calls.log
+scratch/agentbench/results/current.json

browser_automation_cli-0.3.0/AGENTS.md

@@ -0,0 +1,168 @@
+# Agent Integration Guide
+
+> **Give [SKILL.md](./SKILL.md) to your coding agent harness as a skill file. It contains ready-to-use workflows and decision guides for this tool.**
+
+## What This Tool Does
+
+Browser CLI provides authenticated browser automation via a CLI:
+- **`browser-daemon`** — background process owning a headless Chromium and persistent sessions, reachable over a Unix socket
+- **`browser`** — CLI client (~40 ms per call) that sends commands to the daemon, or runs standalone captures
+
+Any coding agent can use it via subprocess calls. No SDK required.
+
+## Install
+
+```bash
+uv tool install browser-automation-cli
+browser install
+```
+
+If `browser` or `browser-daemon` is not found: `export PATH="$HOME/.local/bin:$PATH"`
+
+## Quick Start
+
+```bash
+browser-daemon &                 # 1. start once; headless, nothing opens
+browser create                   # 2. prints an 8-char session id, e.g. abc12345
+browser abc12345 navigate https://github.com/login
+browser abc12345 snapshot        # 3. see what is on the page
+browser abc12345 type --label "Username or email address" octocat
+browser abc12345 click --text "Sign in" -s     # -s: return a fresh snapshot with the result
+```
+
+If a site needs the **user** to log in: `browser abc12345 show` (a window opens), ask the user to log in, then `browser abc12345 hide`. Never ask for credentials.
+
+## Session Model
+
+| Property | Detail |
+|----------|--------|
+| **ID** | 8-char hex (`a1b2c3d4`) |
+| **Scope** | One session = one isolated browser profile (cookies, storage). One session can visit many sites |
+| **Persistence** | Sessions survive daemon restarts (state saved under `~/.browser-daemon/sessions/`). `delete` forgets them |
+| **Idle** | Hidden sessions are frozen (scripts paused) after 10 s idle and hibernated after 10 min; both are transparent — just send the next command |
+| **Visibility** | Headless by default. `create --show`, `show`, `hide` move a session between a window and headless, keeping auth |
+| **Viewport** | 1280x800 desktop; `navigator.webdriver` hidden; UA matches the real Chromium version |
+
+## Command Reference
+
+### Standalone (no daemon)
+
+```bash
+browser capture <url> [-f] [-o path]   # headless JPEG screenshot (viewport; -f full page)
+browser install                        # Chromium runtime
+browser cleanup                        # kill Chromium processes launched by this tool
+```
+
+### Sessions
+
+```bash
+browser create [--show]      # new session (id on stdout)
+browser list [--table]       # JSON: [{session_id, url, title, state, visible}]
+browser <id> show | hide     # window <-> headless
+browser <id> delete
+browser shutdown
+```
+
+### Page commands
+
+Every command prints JSON and exits 1 on failure; `snapshot` prints text. Add `-s`/`--snapshot` to any action to append a fresh snapshot.
+
+| Command | Notes |
+|---------|-------|
+| `navigate <url> [--wait load\|domcontentloaded\|networkidle]` | Returns when the page is usable (`load`). A slow `networkidle` is reported as `settled: false`, not an error |
+| `snapshot [scope-selector] [--all] [--max N] [--json]` | Visible interactive elements and headings, one per line |
+| `click <target> [--double]` | |
+| `type <target> <text> [--sequential] [--submit]` | `--sequential` for autocomplete/combobox inputs; `--submit` presses Enter after |
+| `press <key> [target]` | `Enter`, `Tab`, `Escape`, `Control+a` |
+| `hover <target>` | |
+| `select <target> <value-or-label>` | |
+| `scroll [up\|down] [px]` / `scroll <target>` | |
+| `text [selector]` | Readable text — use for extraction instead of `snapshot --all` |
+| `wait [--text T \| --selector S] [--gone] [--timeout ms]` | |
+| `screenshot [target] [-o path] [-f] [-q 70]` | JPEG under `~/.browser-daemon/shots/` (mode 600) |
+| `eval <js-expression>` | |
+| `console [--clear]` | Buffered console messages |
+| `back` / `forward` | |
+| `batch` | JSON lines on stdin, one round-trip, stops at first failure |
+
+### Targets
+
+| Form | Example |
+|------|---------|
+| ref from snapshot (**preferred**) | `click @e12` |
+| visible text | `click --text "Create"` or `click text=Create` |
+| ARIA role + name | `click --role button --name Create` or `click "role=button[name=Create]"` |
+| form label / placeholder | `type --label "Email" me@x.com`, `type --placeholder Search foo` |
+| CSS / Playwright selector | `click "#submit"`, `click "form >> text=Save"` |
+
+Ambiguous CSS selectors are **refused** (`strict mode violation`) rather than clicking the first match — use a ref or text.
+
+## Reading a snapshot
+
+```
+url: https://dash.cloudflare.com/login
+title: Cloudflare Dashboard | Manage Your Account
+scroll: 0/1400 (viewport 1280x800; [below]/[above] = outside viewport)
+@e2 link "Sign up" href="/sign-up"
+h1 "Sign in to Cloudflare"
+@e7 textbox "Email"
+@e8 textbox "Password" type="password"
+@e10 checkbox "Save email and login method on this device" [checked=false]
+@e11 button "Sign in" [disabled]
+@e30 button "Create" [below]
+```
+
+- `@eN` refs stay valid until the page navigates or the element is removed; a stale ref returns `ref @eN is unknown or stale` — run `snapshot` again.
+- `[below]`/`[above]` elements exist but are outside the viewport; clicking them scrolls automatically.
+- Hidden elements (`display:none`, `aria-hidden`, zero size) are omitted. `--all` adds paragraphs/list items; `--json` adds `box` (x, y, w, h) and a unique CSS `selector`.
+- Large pages: scope with a selector (`snapshot "#main"`) or `--max`.
+
+## Agent Workflow
+
+1. `browser list` — reuse an existing session if one fits.
+2. `browser create` if needed (`--show` only when the user must log in).
+3. `navigate <url> -s` — one call gives you the page and its snapshot.
+4. Act with refs/text: `type @e7 user@x.com`, `click --text "Sign in" -s`.
+5. Verify from the returned snapshot or `text`; take a `screenshot` only when layout matters.
+6. Chain known steps with `batch` to save round-trips:
+   ```bash
+   printf '%s\n' '{"cmd":"type @e7 me@x.com"}' '{"cmd":"type @e8 secret --submit"}' '{"cmd":"snapshot"}' | browser abc12345 batch
+   ```
+
+## Output Parsing
+
+```json
+{"success": true, "url": "https://...", "title": "..."}
+{"success": false, "error": "strict mode violation: locator(\"button.flex\") resolved to 3 elements"}
+```
+
+`snapshot --json` elements: `{ref, role, name, pos, box, href?, value?, placeholder?, checked?, options?, expanded?, selected?, disabled?, required?}`.
+
+### Calling from code
+
+```python
+import subprocess, json
+r = subprocess.run(["browser", "abc12345", "click", "--text", "Create", "-s"], capture_output=True, text=True)
+snapshot_text = r.stdout            # success: snapshot text; failure: JSON with "error", exit code 1
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `Daemon not running` | Start `browser-daemon` |
+| `Session not found` | `browser list` |
+| `ref @eN is unknown or stale` | `snapshot` again |
+| `strict mode violation` | Use `@ref`, `--text`, or a tighter selector |
+| `Timeout … waiting for locator` | Element not visible/enabled — `snapshot` to check state, `wait --text …` |
+| Site shows a login page | `browser <id> show`, ask the user to log in, `hide` |
+| Browser doesn't launch | `browser install` |
+
+## Key Rules for Agents
+
+1. **Never request credentials** — the user logs in manually in a shown window.
+2. **Check `success`** (or the exit code) before proceeding.
+3. **Prefer refs and text targets** over guessed CSS selectors.
+4. **Use `-s` and `batch`** to cut round-trips; use `text` for extraction.
+5. **Reuse sessions**; delete them when no longer needed.
+6. **Leave the daemon running** between actions.

browser_automation_cli-0.3.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.5
+Name: browser-automation-cli
+Version: 0.3.0
+Summary: Browser automation daemon + CLI for coding agents. Persistent sessions, no MCP, no extensions.
+Project-URL: Homepage, https://github.com/jshan9078/browser-automation-cli
+Project-URL: Repository, https://github.com/jshan9078/browser-automation-cli
+Author: Browser CLI Maintainers
+License: 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.
+License-File: LICENSE.txt
+Keywords: agent,automation,browser,cli,playwright
+Requires-Python: >=3.9
+Requires-Dist: playwright>=1.40.0
+Description-Content-Type: text/markdown
+
+# Browser Automation CLI
+
+> **If you are an LLM, see** **[AGENTS.md](https://github.com/jshan9078/browser-automation-cli/blob/main/AGENTS.md)** **for quick setup and usage instructions.**
+
+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.
+
+## Why This Exists
+
+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
+
+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.
+
+## Install
+
+```bash
+uv tool install browser-automation-cli
+browser install
+```
+
+If commands are not found after install, add `~/.local/bin` to your PATH:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## Quick Start
+
+### 1. Start the daemon
+
+```bash
+browser-daemon
+```
+
+Nothing visible opens: the daemon runs Chromium headless. Keep this terminal running (or background it).
+
+### 2. Create a session
+
+```bash
+browser create            # headless session
+browser create --show     # opens a window so you can log in; `browser <id> hide` afterwards
+```
+
+A session is an isolated browser profile (cookies, storage). Log into any sites you need while it is shown; the agent can drive it hidden afterwards. Sessions survive daemon restarts.
+
+### 3. Run browser actions
+
+```bash
+browser <id> navigate https://github.com
+browser <id> snapshot                      # interactive elements, one line each, with @refs
+browser <id> click @e7                     # click by ref from the snapshot
+browser <id> click --text "Sign in"        # or by visible text / role / label
+browser <id> type --label "Username" octocat
+browser <id> screenshot                    # JPEG saved under ~/.browser-daemon/shots/
+```
+
+A snapshot looks like this (Cloudflare login, 245 tokens):
+
+```
+url: https://dash.cloudflare.com/login
+title: Cloudflare Dashboard | Manage Your Account
+@e2 link "Sign up" href="/sign-up"
+h1 "Sign in to Cloudflare"
+@e3 button "Continue with Google"
+@e7 textbox "Email"
+@e8 textbox "Password" type="password"
+@e10 checkbox "Save email and login method on this device"
+@e11 button "Sign in" [disabled]
+```
+
+### 4. Manage sessions
+
+```bash
+browser list                  # JSON (--table for humans)
+browser <id> show | hide      # move between a visible window and headless
+browser <id> delete
+browser shutdown              # stop the daemon; sessions are saved and restored next start
+```
+
+***
+
+## Commands Reference
+
+### Standalone (no daemon)
+
+```bash
+browser capture <url> [-f] [-o <path>]     # headless viewport screenshot (-f = full page)
+browser install                            # download Chromium (~170 MB)
+browser cleanup                            # kill Chromium processes launched from Playwright's cache
+```
+
+### Sessions
+
+| Command | Description |
+| :-- | :-- |
+| `browser create [--show]` | New session; `--show` opens a window (for manual login) |
+| `browser list [--table]` | Sessions with `state` (active / frozen / hibernated) and `visible` |
+| `browser <id> show` / `hide` | Move the session to a visible window / back to headless (auth kept) |
+| `browser <id> delete` | Close session and forget its cookies |
+| `browser shutdown` | Stop the daemon gracefully |
+| `browser --version` / `browser update` | Show version; upgrade to the latest PyPI release. The daemon checks PyPI once a day and the CLI prints a one-line hint on stderr when a newer version exists (`BROWSER_NO_UPDATE_CHECK=1` disables) |
+
+### Page commands
+
+All print JSON (snapshot prints text). Add `-s` / `--snapshot` to any action to get a fresh snapshot in the same call.
+
+| Command | Description |
+| :-- | :-- |
+| `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]` | |
+| `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>` | |
+| `select <target> <value-or-label>` | |
+| `scroll [up\|down] [px]` / `scroll <target>` | |
+| `text [selector]` | Readable text of the page or an element (cheap extraction) |
+| `wait [--text T \| --selector S] [--gone] [--timeout ms]` | |
+| `screenshot [target] [-o path] [-f] [-q 70]` | JPEG; element screenshots via any target |
+| `eval <js>` | Evaluate an expression in the page |
+| `console [--clear]` | Buffered console messages |
+| `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.
+
+***
+
+## 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.
+* **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 [OPTIMIZATION.md](OPTIMIZATION.md) for the measurements.
+
+## Anti-Detection
+
+* `navigator.webdriver` hidden via `add_init_script`
+* Desktop Chrome user agent derived from the actual Chromium version
+* 1280x800 viewport (desktop layouts; same size Anthropic/OpenAI computer-use tooling targets)
+
+## Output Format
+
+Action responses:
+
+```json
+{"success": true, "url": "https://github.com", "title": "GitHub"}
+```
+
+Errors (exit code 1):
+
+```json
+{"success": false, "error": "ref @e9 is unknown or stale (page changed); run snapshot again"}
+```
+
+`snapshot --json`:
+
+```json
+{"success": true, "url": "...", "title": "...", "scrollY": 0, "viewportHeight": 800, "viewportWidth": 1280, "documentHeight": 2400,
+ "elements": [{"ref": "e3", "role": "button", "name": "Create", "pos": "", "box": [912, 640, 88, 36]}]}
+```
+
+## Using with Coding Agents
+
+Share [`SKILL.md`](SKILL.md) with your coding agent harness; see [AGENTS.md](AGENTS.md) for the integration guide.
+
+## Rust implementation (preview)
+
+`rust/` contains a Rust client and daemon with the same CLI and socket protocol — no Python, Playwright or
+Node at runtime (Chromium from `browser install` or `BROWSER_CHROME_PATH` is still required). Per-call
+overhead 40 ms → 2 ms, daemon RSS −90 MB, frame- and shadow-DOM-aware snapshots. See OPTIMIZATION.md §7.
+
+```bash
+cd rust && cargo build --release
+./target/release/browser-daemon &      # drop-in for the Python daemon
+./target/release/browser list
+```
+
+## 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>
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+| :-- | :-- |
+| `Command not found: browser` | `export PATH="$HOME/.local/bin:$PATH"` |
+| `Daemon not running` | `browser-daemon` |
+| 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 (preview, macOS arm64 build only for now)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jshan9078/browser-automation-cli/main/rust/install.sh | sh
+```
+
+Installs `browser` and `browser-daemon` into `~/.local/bin` (set `BROWSER_CLI_BIN` to change). Other platforms: `cd rust && 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`. Publishing the Rust build to PyPI is
+planned for 0.4.0 once Linux/Windows wheels are built in CI; until then the PyPI package is the Python
+implementation and the Rust wheel is attached to the GitHub release.

browser_automation_cli-0.3.0/README.md

@@ -0,0 +1,215 @@
+# Browser Automation CLI
+
+> **If you are an LLM, see** **[AGENTS.md](https://github.com/jshan9078/browser-automation-cli/blob/main/AGENTS.md)** **for quick setup and usage instructions.**
+
+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.
+
+## Why This Exists
+
+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
+
+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.
+
+## Install
+
+```bash
+uv tool install browser-automation-cli
+browser install
+```
+
+If commands are not found after install, add `~/.local/bin` to your PATH:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## Quick Start
+
+### 1. Start the daemon
+
+```bash
+browser-daemon
+```
+
+Nothing visible opens: the daemon runs Chromium headless. Keep this terminal running (or background it).
+
+### 2. Create a session
+
+```bash
+browser create            # headless session
+browser create --show     # opens a window so you can log in; `browser <id> hide` afterwards
+```
+
+A session is an isolated browser profile (cookies, storage). Log into any sites you need while it is shown; the agent can drive it hidden afterwards. Sessions survive daemon restarts.
+
+### 3. Run browser actions
+
+```bash
+browser <id> navigate https://github.com
+browser <id> snapshot                      # interactive elements, one line each, with @refs
+browser <id> click @e7                     # click by ref from the snapshot
+browser <id> click --text "Sign in"        # or by visible text / role / label
+browser <id> type --label "Username" octocat
+browser <id> screenshot                    # JPEG saved under ~/.browser-daemon/shots/
+```
+
+A snapshot looks like this (Cloudflare login, 245 tokens):
+
+```
+url: https://dash.cloudflare.com/login
+title: Cloudflare Dashboard | Manage Your Account
+@e2 link "Sign up" href="/sign-up"
+h1 "Sign in to Cloudflare"
+@e3 button "Continue with Google"
+@e7 textbox "Email"
+@e8 textbox "Password" type="password"
+@e10 checkbox "Save email and login method on this device"
+@e11 button "Sign in" [disabled]
+```
+
+### 4. Manage sessions
+
+```bash
+browser list                  # JSON (--table for humans)
+browser <id> show | hide      # move between a visible window and headless
+browser <id> delete
+browser shutdown              # stop the daemon; sessions are saved and restored next start
+```
+
+***
+
+## Commands Reference
+
+### Standalone (no daemon)
+
+```bash
+browser capture <url> [-f] [-o <path>]     # headless viewport screenshot (-f = full page)
+browser install                            # download Chromium (~170 MB)
+browser cleanup                            # kill Chromium processes launched from Playwright's cache
+```
+
+### Sessions
+
+| Command | Description |
+| :-- | :-- |
+| `browser create [--show]` | New session; `--show` opens a window (for manual login) |
+| `browser list [--table]` | Sessions with `state` (active / frozen / hibernated) and `visible` |
+| `browser <id> show` / `hide` | Move the session to a visible window / back to headless (auth kept) |
+| `browser <id> delete` | Close session and forget its cookies |
+| `browser shutdown` | Stop the daemon gracefully |
+| `browser --version` / `browser update` | Show version; upgrade to the latest PyPI release. The daemon checks PyPI once a day and the CLI prints a one-line hint on stderr when a newer version exists (`BROWSER_NO_UPDATE_CHECK=1` disables) |
+
+### Page commands
+
+All print JSON (snapshot prints text). Add `-s` / `--snapshot` to any action to get a fresh snapshot in the same call.
+
+| Command | Description |
+| :-- | :-- |
+| `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]` | |
+| `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>` | |
+| `select <target> <value-or-label>` | |
+| `scroll [up\|down] [px]` / `scroll <target>` | |
+| `text [selector]` | Readable text of the page or an element (cheap extraction) |
+| `wait [--text T \| --selector S] [--gone] [--timeout ms]` | |
+| `screenshot [target] [-o path] [-f] [-q 70]` | JPEG; element screenshots via any target |
+| `eval <js>` | Evaluate an expression in the page |
+| `console [--clear]` | Buffered console messages |
+| `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.
+
+***
+
+## 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.
+* **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 [OPTIMIZATION.md](OPTIMIZATION.md) for the measurements.
+
+## Anti-Detection
+
+* `navigator.webdriver` hidden via `add_init_script`
+* Desktop Chrome user agent derived from the actual Chromium version
+* 1280x800 viewport (desktop layouts; same size Anthropic/OpenAI computer-use tooling targets)
+
+## Output Format
+
+Action responses:
+
+```json
+{"success": true, "url": "https://github.com", "title": "GitHub"}
+```
+
+Errors (exit code 1):
+
+```json
+{"success": false, "error": "ref @e9 is unknown or stale (page changed); run snapshot again"}
+```
+
+`snapshot --json`:
+
+```json
+{"success": true, "url": "...", "title": "...", "scrollY": 0, "viewportHeight": 800, "viewportWidth": 1280, "documentHeight": 2400,
+ "elements": [{"ref": "e3", "role": "button", "name": "Create", "pos": "", "box": [912, 640, 88, 36]}]}
+```
+
+## Using with Coding Agents
+
+Share [`SKILL.md`](SKILL.md) with your coding agent harness; see [AGENTS.md](AGENTS.md) for the integration guide.
+
+## Rust implementation (preview)
+
+`rust/` contains a Rust client and daemon with the same CLI and socket protocol — no Python, Playwright or
+Node at runtime (Chromium from `browser install` or `BROWSER_CHROME_PATH` is still required). Per-call
+overhead 40 ms → 2 ms, daemon RSS −90 MB, frame- and shadow-DOM-aware snapshots. See OPTIMIZATION.md §7.
+
+```bash
+cd rust && cargo build --release
+./target/release/browser-daemon &      # drop-in for the Python daemon
+./target/release/browser list
+```
+
+## 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>
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+| :-- | :-- |
+| `Command not found: browser` | `export PATH="$HOME/.local/bin:$PATH"` |
+| `Daemon not running` | `browser-daemon` |
+| 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 (preview, macOS arm64 build only for now)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jshan9078/browser-automation-cli/main/rust/install.sh | sh
+```
+
+Installs `browser` and `browser-daemon` into `~/.local/bin` (set `BROWSER_CLI_BIN` to change). Other platforms: `cd rust && 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`. Publishing the Rust build to PyPI is
+planned for 0.4.0 once Linux/Windows wheels are built in CI; until then the PyPI package is the Python
+implementation and the Rust wheel is attached to the GitHub release.