Browser Automation CLI

If you are an LLM, see 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 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

uv tool install browser-automation-cli
browser install

If commands are not found after install, add ~/.local/bin to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Quick Start

1. Start the daemon

browser-daemon

Nothing visible opens: the daemon runs Chromium headless. Keep this terminal running (or background it).

2. Create a session

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

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

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)

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

Page commands

All print JSON (snapshot prints text). Add -s / --snapshot to any action to get a fresh snapshot in the same call.

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 shown.
• 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 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:

{"success": true, "url": "https://github.com", "title": "GitHub"}

Errors (exit code 1):

{"success": false, "error": "ref @e9 is unknown or stale (page changed); run snapshot again"}

snapshot --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 with your coding agent harness; see 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.

cd rust && cargo build --release
./target/release/browser-daemon &      # drop-in for the Python daemon
./target/release/browser list

Development

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

Installing the Rust binaries (preview, macOS arm64 build only for now)

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.