[ { "path": ".changeset/README.md", "content": "# Changesets\n\nThis project uses [Changesets](https://github.com/changesets/changesets) for versioning and changelog generation.\n\n## Adding a changeset\n\nWhen you make a change that should be released, run:\n\n```bash\npnpm changeset\n```\n\nThis will prompt you to:\n1. Select the type of change (patch, minor, major)\n2. Write a summary of your changes\n\nThe changeset file will be committed with your PR.\n\n## Release process\n\nWhen changesets are merged to `main`, the release workflow will:\n1. Create a \"Version Packages\" PR that updates version numbers and changelogs\n2. When that PR is merged, packages are automatically published to npm\n" }, { "path": ".changeset/config.json", "content": "{\n \"$schema\": \"https://unpkg.com/@changesets/config@3.1.1/schema.json\",\n \"changelog\": \"@changesets/cli/changelog\",\n \"commit\": false,\n \"fixed\": [],\n \"linked\": [],\n \"access\": \"public\",\n \"baseBranch\": \"main\",\n \"updateInternalDependencies\": \"patch\",\n \"ignore\": []\n}\n" }, { "path": ".claude-plugin/marketplace.json", "content": "{\n \"$schema\": \"https://anthropic.com/claude-code/marketplace.schema.json\",\n \"name\": \"agent-browser\",\n \"description\": \"Headless browser automation for AI agents\",\n \"owner\": {\n \"name\": \"Vercel\",\n \"email\": \"support@vercel.com\"\n },\n \"plugins\": [\n {\n \"name\": \"agent-browser\",\n \"description\": \"Automates browser interactions for web testing, form filling, screenshots, and data extraction\",\n \"source\": \"./\",\n \"strict\": false,\n \"skills\": [\"./skills/agent-browser\"],\n \"category\": \"development\"\n }\n ]\n}\n" }, { "path": ".github/workflows/ci.yml", "content": "name: CI\n\non:\n push:\n branches: [main]\n pull_request:\n branches: [main]\n workflow_dispatch:\n\njobs:\n version-sync:\n name: Version Sync Check\n runs-on: ubuntu-latest\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n\n - name: Check version sync\n run: node scripts/check-version-sync.js\n\n rust:\n name: Rust\n runs-on: ubuntu-latest\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n\n - name: Setup Rust toolchain\n uses: dtolnay/rust-toolchain@stable\n with:\n components: rustfmt, clippy\n\n - name: Cache Rust build artifacts\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: cli\n\n - name: Format check\n run: cargo fmt --manifest-path cli/Cargo.toml -- --check\n\n - name: Clippy check\n run: cargo clippy --manifest-path cli/Cargo.toml -- -D warnings\n\n - name: Run Rust tests\n run: cargo test --profile ci --manifest-path cli/Cargo.toml\n\n rust-cross:\n name: Rust (${{ matrix.os }} - ${{ matrix.target }})\n if: github.event_name != 'pull_request'\n runs-on: ${{ matrix.os }}\n strategy:\n matrix:\n include:\n - os: macos-latest\n target: aarch64-apple-darwin\n - os: macos-latest\n target: x86_64-apple-darwin\n - os: windows-latest\n target: x86_64-pc-windows-msvc\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n\n - name: Setup Rust toolchain\n uses: dtolnay/rust-toolchain@stable\n with:\n targets: ${{ matrix.target }}\n\n - name: Cache Rust build artifacts\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: cli\n\n - name: Run Rust tests\n run: cargo test --profile ci --manifest-path cli/Cargo.toml --target ${{ matrix.target }}\n\n native-e2e:\n name: Native E2E Tests\n if: github.event_name != 'pull_request'\n runs-on: ubuntu-latest\n needs: rust\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n\n - name: Setup Rust toolchain\n uses: dtolnay/rust-toolchain@stable\n\n - name: Cache Rust build artifacts\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: cli\n\n - name: Install Chrome\n run: |\n cargo run --manifest-path cli/Cargo.toml -- install --with-deps\n\n - name: Run e2e tests\n run: cargo test --profile ci --manifest-path cli/Cargo.toml e2e -- --ignored --test-threads=1\n\n windows-integration:\n name: Windows Integration Test\n if: github.event_name != 'pull_request'\n runs-on: windows-latest\n needs: rust-cross\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n\n - name: Setup Rust toolchain\n uses: dtolnay/rust-toolchain@stable\n with:\n targets: x86_64-pc-windows-msvc\n\n - name: Cache Rust build artifacts\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: cli\n\n - name: Build Rust CLI\n run: cargo build --release --manifest-path cli/Cargo.toml --target x86_64-pc-windows-msvc\n\n - name: Copy CLI binary to bin directory\n run: |\n Copy-Item cli/target/x86_64-pc-windows-msvc/release/agent-browser.exe bin/agent-browser-win32-x64.exe\n\n - name: Test agent-browser install command\n run: |\n $env:PATH = \"$pwd\\bin;$env:PATH\"\n for ($i = 1; $i -le 3; $i++) {\n bin/agent-browser-win32-x64.exe install\n if ($LASTEXITCODE -eq 0) { exit 0 }\n Write-Host \"Attempt $i failed, retrying in 10 seconds...\"\n Start-Sleep -Seconds 10\n }\n exit 1\n shell: pwsh\n timeout-minutes: 10\n\n - name: Test daemon lifecycle (open, snapshot, close)\n run: |\n $env:PATH = \"$pwd\\bin;$env:PATH\"\n Write-Host \"--- Opening page ---\"\n bin/agent-browser-win32-x64.exe open https://example.com\n if ($LASTEXITCODE -ne 0) { Write-Error \"open failed\"; exit 1 }\n Write-Host \"--- Taking snapshot ---\"\n $snapshot = bin/agent-browser-win32-x64.exe snapshot\n if ($LASTEXITCODE -ne 0) { Write-Error \"snapshot failed\"; exit 1 }\n Write-Host $snapshot\n Write-Host \"--- Closing browser ---\"\n bin/agent-browser-win32-x64.exe close\n if ($LASTEXITCODE -ne 0) { Write-Error \"close failed\"; exit 1 }\n Write-Host \"--- Windows daemon lifecycle test passed ---\"\n shell: pwsh\n timeout-minutes: 5\n\n global-install:\n name: Global Install (${{ matrix.os }})\n if: github.event_name != 'pull_request'\n runs-on: ${{ matrix.os }}\n needs: rust-cross\n strategy:\n matrix:\n include:\n - os: ubuntu-latest\n target: x86_64-unknown-linux-gnu\n binary: agent-browser-linux-x64\n - os: macos-latest\n target: aarch64-apple-darwin\n binary: agent-browser-darwin-arm64\n - os: windows-latest\n target: x86_64-pc-windows-msvc\n binary: agent-browser-win32-x64.exe\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n\n - name: Setup Node.js\n uses: actions/setup-node@v4\n with:\n node-version: 22\n\n - name: Setup Rust toolchain\n uses: dtolnay/rust-toolchain@stable\n with:\n targets: ${{ matrix.target }}\n\n - name: Cache Rust build artifacts\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: cli\n\n - name: Build Rust CLI\n run: cargo build --release --manifest-path cli/Cargo.toml --target ${{ matrix.target }}\n\n - name: Copy CLI binary to bin directory (Unix)\n if: runner.os != 'Windows'\n run: cp cli/target/${{ matrix.target }}/release/agent-browser bin/${{ matrix.binary }}\n\n - name: Copy CLI binary to bin directory (Windows)\n if: runner.os == 'Windows'\n run: Copy-Item cli/target/${{ matrix.target }}/release/agent-browser.exe bin/${{ matrix.binary }}\n\n - name: Test npm global install\n run: |\n npm pack\n npm install -g agent-browser-*.tgz\n agent-browser --version\n shell: bash\n\n - name: Verify symlink points to native binary (Unix)\n if: runner.os != 'Windows'\n run: |\n SYMLINK=$(npm prefix -g)/bin/agent-browser\n TARGET=$(readlink \"$SYMLINK\")\n echo \"Symlink: $SYMLINK\"\n echo \"Target: $TARGET\"\n if [[ \"$TARGET\" != *\"${{ matrix.binary }}\"* ]]; then\n echo \"ERROR: Symlink should point to native binary, not JS wrapper\"\n exit 1\n fi\n echo \"Symlink correctly points to native binary\"\n shell: bash\n\n - name: Verify shim points to native binary (Windows)\n if: runner.os == 'Windows'\n run: |\n $shimPath = \"$(npm prefix -g)\\agent-browser.cmd\"\n $content = Get-Content $shimPath -Raw\n echo \"Shim path: $shimPath\"\n echo \"Shim content:\"\n echo $content\n if ($content -notmatch \"agent-browser-win32-x64\\.exe\") {\n echo \"ERROR: Shim should point to native .exe, not JS wrapper\"\n exit 1\n }\n echo \"Shim correctly points to native binary\"\n shell: pwsh\n" }, { "path": ".github/workflows/release.yml", "content": "name: Release\n\non:\n push:\n branches:\n - main\n workflow_dispatch:\n\nconcurrency: ${{ github.workflow }}-${{ github.ref }}\n\npermissions:\n contents: write\n pull-requests: write\n\njobs:\n # Build native binaries for all platforms first\n build-binaries:\n name: Build ${{ matrix.name }}\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n matrix:\n include:\n - name: Linux x64\n os: ubuntu-latest\n target: x86_64-unknown-linux-gnu\n binary: agent-browser-linux-x64\n use_zigbuild: true\n - name: Linux ARM64\n os: ubuntu-latest\n target: aarch64-unknown-linux-gnu\n binary: agent-browser-linux-arm64\n use_zigbuild: true\n - name: Linux musl x64\n os: ubuntu-latest\n target: x86_64-unknown-linux-musl\n binary: agent-browser-linux-musl-x64\n use_zigbuild: true\n - name: Linux musl ARM64\n os: ubuntu-latest\n target: aarch64-unknown-linux-musl\n binary: agent-browser-linux-musl-arm64\n use_zigbuild: true\n - name: Windows x64\n os: ubuntu-latest\n target: x86_64-pc-windows-gnu\n binary: agent-browser-win32-x64.exe\n use_zigbuild: false\n - name: macOS x64\n os: macos-latest\n target: x86_64-apple-darwin\n binary: agent-browser-darwin-x64\n use_zigbuild: false\n - name: macOS ARM64\n os: macos-latest\n target: aarch64-apple-darwin\n binary: agent-browser-darwin-arm64\n use_zigbuild: false\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n\n - name: Setup pnpm\n uses: pnpm/action-setup@v4\n with:\n version: 9\n\n - name: Setup Node.js\n uses: actions/setup-node@v4\n with:\n node-version: '22'\n cache: pnpm\n\n - name: Install npm dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Sync version\n run: pnpm run version:sync\n\n - name: Setup Rust toolchain\n uses: dtolnay/rust-toolchain@stable\n with:\n targets: ${{ matrix.target }}\n\n - name: Install cross-compilation tools (Linux)\n if: runner.os == 'Linux'\n run: |\n sudo apt-get update\n sudo apt-get install -y gcc-aarch64-linux-gnu gcc-x86-64-linux-gnu mingw-w64\n\n - name: Install cargo-zigbuild\n if: matrix.use_zigbuild\n run: |\n pip3 install ziglang\n cargo install cargo-zigbuild\n\n - name: Configure Rust linkers\n if: runner.os == 'Linux'\n run: |\n mkdir -p ~/.cargo\n cat >> ~/.cargo/config.toml << 'EOF'\n [target.aarch64-unknown-linux-gnu]\n linker = \"aarch64-linux-gnu-gcc\"\n\n [target.x86_64-pc-windows-gnu]\n linker = \"x86_64-w64-mingw32-gcc\"\n EOF\n\n - name: Cache Rust build artifacts\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: cli\n\n - name: Build with zigbuild\n if: matrix.use_zigbuild\n run: cargo zigbuild --release --manifest-path cli/Cargo.toml --target ${{ matrix.target }}\n\n - name: Build with cargo\n if: '!matrix.use_zigbuild'\n run: cargo build --release --manifest-path cli/Cargo.toml --target ${{ matrix.target }}\n\n - name: Copy binary\n run: |\n mkdir -p artifacts\n if [[ \"${{ matrix.target }}\" == *\"windows\"* ]]; then\n cp cli/target/${{ matrix.target }}/release/agent-browser.exe artifacts/${{ matrix.binary }}\n else\n cp cli/target/${{ matrix.target }}/release/agent-browser artifacts/${{ matrix.binary }}\n chmod +x artifacts/${{ matrix.binary }}\n fi\n\n - name: Upload artifact\n uses: actions/upload-artifact@v4\n with:\n name: ${{ matrix.binary }}\n path: artifacts/${{ matrix.binary }}\n retention-days: 7\n\n # Create release PR or publish to npm (with binaries)\n release:\n name: Release\n needs: build-binaries\n runs-on: ubuntu-latest\n outputs:\n published: ${{ steps.changesets.outputs.published }}\n publishedPackages: ${{ steps.changesets.outputs.publishedPackages }}\n steps:\n - name: Checkout Repo\n uses: actions/checkout@v4\n with:\n fetch-depth: 0\n\n - name: Setup pnpm\n uses: pnpm/action-setup@v4\n with:\n version: 9\n\n - name: Setup Node.js\n uses: actions/setup-node@v4\n with:\n node-version: '22'\n cache: pnpm\n registry-url: 'https://registry.npmjs.org'\n\n - name: Install Dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Download all binary artifacts\n uses: actions/download-artifact@v4\n with:\n path: artifacts/\n\n - name: Move binaries to bin directory\n run: |\n mkdir -p bin\n find artifacts -type f -name 'agent-browser-*' -exec mv {} bin/ \\;\n rm -rf artifacts\n chmod +x bin/agent-browser-* 2>/dev/null || true\n echo \"Binaries in bin/:\"\n ls -la bin/\n\n - name: Verify all binaries exist\n run: |\n EXPECTED_BINARIES=(\n \"agent-browser-linux-x64\"\n \"agent-browser-linux-arm64\"\n \"agent-browser-linux-musl-x64\"\n \"agent-browser-linux-musl-arm64\"\n \"agent-browser-win32-x64.exe\"\n \"agent-browser-darwin-x64\"\n \"agent-browser-darwin-arm64\"\n )\n MIN_SIZE=100000 # Binaries should be at least 100KB\n ERRORS=0\n for binary in \"${EXPECTED_BINARIES[@]}\"; do\n if [ ! -f \"bin/$binary\" ]; then\n echo \"ERROR: Missing bin/$binary\"\n ERRORS=$((ERRORS + 1))\n else\n SIZE=$(stat -c%s \"bin/$binary\" 2>/dev/null || stat -f%z \"bin/$binary\")\n if [ \"$SIZE\" -lt \"$MIN_SIZE\" ]; then\n echo \"ERROR: bin/$binary is too small ($SIZE bytes, expected >= $MIN_SIZE)\"\n ERRORS=$((ERRORS + 1))\n else\n echo \"OK: bin/$binary ($SIZE bytes)\"\n fi\n fi\n done\n if [ \"$ERRORS\" -gt 0 ]; then\n echo \"Error: $ERRORS binary issues found\"\n exit 1\n fi\n echo \"All 7 platform binaries present and valid\"\n\n - name: Create Release Pull Request or Publish to npm\n id: changesets\n uses: changesets/action@v1\n with:\n version: pnpm ci:version\n publish: pnpm ci:publish\n title: 'chore: version packages'\n commit: 'chore: version packages'\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n NODE_AUTH_TOKEN: ${{ secrets.NPM_VERCEL_TOKEN_ELEVATED }}\n\n # Create GitHub release with binaries after npm publish\n github-release:\n name: Create GitHub Release\n needs: release\n if: needs.release.outputs.published == 'true'\n runs-on: ubuntu-latest\n steps:\n - name: Checkout Repo\n uses: actions/checkout@v4\n with:\n ref: main\n\n - name: Download all artifacts\n uses: actions/download-artifact@v4\n with:\n path: artifacts/\n\n - name: Move binaries to bin directory\n run: |\n mkdir -p bin\n find artifacts -type f -name 'agent-browser-*' -exec mv {} bin/ \\;\n rm -rf artifacts\n chmod +x bin/agent-browser-* 2>/dev/null || true\n ls -la bin/\n\n - name: Verify binaries exist\n run: |\n BINARY_COUNT=$(ls bin/agent-browser-* 2>/dev/null | wc -l)\n if [ \"$BINARY_COUNT\" -lt 7 ]; then\n echo \"Error: Expected 7 binaries, found $BINARY_COUNT\"\n ls -la bin/\n exit 1\n fi\n echo \"Found $BINARY_COUNT binaries\"\n\n - name: Create GitHub Release\n run: |\n VERSION=$(node -p \"require('./package.json').version\")\n TAG=\"v$VERSION\"\n \n # Check if release already exists\n if gh release view \"$TAG\" &>/dev/null; then\n echo \"Release $TAG already exists, uploading binaries...\"\n gh release upload \"$TAG\" bin/agent-browser-* --clobber\n else\n echo \"Creating release $TAG...\"\n gh release create \"$TAG\" \\\n --title \"$TAG\" \\\n --generate-notes \\\n bin/agent-browser-*\n fi\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".gitignore", "content": "# Dependencies\nnode_modules/\n\n# Build output\ndist/\n\n# Native binaries (keep the launcher scripts)\nbin/agent-browser-*\n!bin/agent-browser\n!bin/agent-browser.cmd\n\n# Rust build artifacts\ncli/target/\ncli/*.o\n\n# Logs\n*.log\nnpm-debug.log*\n\n# IDE\n.idea/\n.vscode/\n*.swp\n*.swo\n\n# OS\n.DS_Store\nThumbs.db\n\n# Python\n__pycache__/\n\n# Test artifacts\n*.png\n*.jpeg\n*.jpg\n*.webm\ntest/e2e/.dogfood-output/\n\n# Package manager\npackage-lock.json\nyarn.lock\n\n# Environment\n.env\n.env.local\n\n# opensrc - source code for packages\nopensrc/\n\n# Docs site\ndocs/node_modules/\ndocs/.next/\ndocs/out/\ndocs/package-lock.json\n\n# pnpm\n.pnpm-store/\n" }, { "path": ".husky/pre-commit", "content": "node scripts/sync-version.js\ngit add cli/Cargo.toml cli/Cargo.lock\n" }, { "path": ".prettierrc", "content": "{\n \"semi\": true,\n \"singleQuote\": true,\n \"trailingComma\": \"es5\",\n \"printWidth\": 100,\n \"tabWidth\": 2\n}\n" }, { "path": "AGENTS.md", "content": "# AGENTS.md\n\nInstructions for AI coding agents working with this codebase.\n\n## Package Manager\n\nThis project uses **pnpm**. Always use `pnpm` instead of `npm` or `yarn` for installing dependencies, running scripts, etc. (e.g., `pnpm install`, `pnpm run build`).\n\n## Code Style\n\n- Do not use emojis in code, output, or documentation. Unicode symbols (✓, ✗, →, ⚠) are acceptable.\n- CLI colored output uses `cli/src/color.rs`. This module respects the `NO_COLOR` environment variable. Never use hardcoded ANSI color codes.\n- CLI flags must always use kebab-case (e.g., `--auto-connect`, `--allow-file-access`). Never use camelCase for flags (e.g., `--autoConnect` is wrong).\n\n## Documentation\n\nWhen adding or changing user-facing features (new flags, commands, behaviors, environment variables, etc.), update **all** of the following:\n\n1. `cli/src/output.rs` -- `--help` output (flags list, examples, environment variables)\n2. `README.md` -- Options table, relevant feature sections, examples\n3. `skills/agent-browser/SKILL.md` -- so AI agents know about the feature\n4. `docs/src/app/` -- the Next.js docs site (MDX pages)\n5. Inline doc comments in the relevant source files\n\nThis applies to changes that either human users or AI agents would need to know about. Do not skip any of these locations.\n\nIn the `docs/src/app/` MDX files, always use HTML `` syntax for tables (not markdown pipe tables). This matches the existing convention across the docs site.\n\n## Architecture\n\nThis is a Rust codebase. The browser automation daemon lives in `cli/src/native/` (daemon, actions, browser, CDP client, snapshot, state). The `--engine` flag selects Chrome vs Lightpanda. The `install` command downloads Chrome from Chrome for Testing directly.\n\n## Testing\n\n### Unit Tests\n\n```bash\ncd cli && cargo test\n```\n\nRuns all unit tests (~320 tests). These are fast and don't require Chrome.\n\n### End-to-End Tests\n\n```bash\ncd cli && cargo test e2e -- --ignored --test-threads=1\n```\n\nRuns 18 e2e tests that launch real headless Chrome instances and exercise the full native daemon command pipeline. Requirements:\n\n- Chrome must be installed\n- Must run serially (`--test-threads=1`) to avoid Chrome instance contention\n- Tests are `#[ignore]`'d so they don't run during normal `cargo test`\n\nThe e2e tests live in `cli/src/native/e2e_tests.rs` and cover: launch/close, navigation, snapshots, screenshots, form interaction, cookies, storage, tabs, element queries, viewport/emulation, domain filtering, diff, state management, error handling, and Phase 8 commands.\n\n### Linting and Formatting\n\n```bash\ncd cli && cargo fmt -- --check # Check formatting\ncd cli && cargo clippy # Lint\n```\n\n\n\n## Source Code Reference\n\nSource code for dependencies is available in `opensrc/` for deeper understanding of implementation details.\n\nSee `opensrc/sources.json` for the list of available packages and their versions.\n\nUse this source code when you need to understand how a package works internally, not just its types/interface.\n\n### Fetching Additional Source Code\n\nTo fetch source code for a package or repository you need to understand, run:\n\n```bash\nnpx opensrc # npm package (e.g., npx opensrc zod)\nnpx opensrc pypi: # Python package (e.g., npx opensrc pypi:requests)\nnpx opensrc crates: # Rust crate (e.g., npx opensrc crates:serde)\nnpx opensrc / # GitHub repo (e.g., npx opensrc vercel/ai)\n```\n\n\n" }, { "path": "CHANGELOG.md", "content": "# agent-browser\n\n## 0.21.2\n\n### Patch Changes\n\n- 757626f: ### Bug Fixes\n\n - **Deduplicate text content in snapshots** - Fixed an issue where duplicate text content appeared in page snapshots (#909)\n - **Native mouse drag state** - Fixed incorrect raw native mouse drag state not being properly tracked across `down`, `move`, and `up` events (#872)\n - **Chrome headless launch failures** - Fixed browser launch failures caused by the `--enable-unsafe-swiftshader` flag in Chrome headless mode (#915)\n - **Origin-scoped `--headers` persistence** - Restored correct persistence of origin-scoped headers set via `--headers` across navigation commands (#894)\n - **Relative URLs in WebSocket domain filter** - Fixed handling of relative URLs in the WebSocket domain filter script (#624)\n\n## 0.21.1\n\n### Patch Changes\n\n- 1e7619d: ### New Features\n\n - **HAR 1.2 network capture** - Added commands to capture and export network traffic in HAR 1.2 format, including accurate request/response timing, headers, body sizes, and resource types sourced from Chrome DevTools Protocol events (#864)\n - **Built-in `upgrade` command** - Added `agent-browser upgrade` to self-update the CLI; automatically detects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command (#898)\n\n ### Documentation\n\n - Added `upgrade` command to the README command reference and installation guide\n - Added a dedicated **Updating** section to the README with usage instructions for `agent-browser upgrade`\n\n## 0.21.0\n\n### Minor Changes\n\n- c6de80b: ### New Features\n\n - **`batch` command** -- Execute multiple commands from stdin in a single invocation. Accepts a JSON array of string arrays and returns results sequentially. Supports `--bail` to stop on first error and `--json` for structured output (#865)\n - **iframe support** -- CLI interactions and snapshots now traverse into iframe content, enabling automation of cross-frame pages (#869)\n - **`network har start/stop` command** -- Capture and export network traffic in HAR 1.2 format (#874)\n - **WebSocket fallback for CDP discovery** -- When HTTP-based CDP endpoint discovery fails, the CLI now falls back to a WebSocket connection automatically (#873)\n\n ### Improvements\n\n - **`--full`/`-f` refactored to command-level flag** -- Moved from a global flag to a per-command flag for clearer scoping (#877)\n - **Enhanced Chrome launch** -- Added `--user-data-dir` support and configurable launch timeout for more reliable browser startup (#852)\n\n ### Bug Fixes\n\n - Fixed `/json/list` fallback when `/json/version` endpoint is unavailable, improving compatibility with non-standard CDP implementations (#861)\n - Fixed daemon liveness detection for PID namespace isolation (e.g. `unshare`). Uses socket connectivity as the sole liveness check instead of `kill(pid, 0)`, which fails when the caller cannot see the daemon's PID (#879)\n - Fixed Ubuntu dependency install accidentally removing system packages (#884)\n\n## 0.20.14\n\n### Patch Changes\n\n- c0d4cf6: ### New Features\n\n - **Idle timeout for daemon auto-shutdown** - Added `--idle-timeout` CLI flag (and `AGENT_BROWSER_IDLE_TIMEOUT_MS` environment variable) to automatically shut down the daemon after a period of inactivity. Accepts human-friendly formats such as `10s`, `3m`, `1h`, or raw milliseconds (#856)\n - **Cursor-interactive elements in snapshot tree** - Cursor-interactive elements are now embedded directly into the snapshot tree for richer context (#855)\n\n ### Bug Fixes\n\n - Fixed **remote host support** in CDP discovery, enabling connection to browsers running on non-local hosts (#854)\n - Fixed **CDP flag propagation** to the daemon process, ensuring reliable CDP reconnection across sessions (#857)\n - Fixed **Windows auto-connect profiling** to correctly handle browser connection on Windows (#835, #840)\n - Fixed **Windows transient error detection** by recognising Windows-specific socket error codes (`os error 10061` connection refused, `os error 10054` connection reset) during daemon reconnection attempts\n\n## 0.20.13\n\n### Patch Changes\n\n- eda956b: ### Bug Fixes\n\n - **Network idle detection for cached pages** - Fixed an issue where `poll_network_idle` could return immediately when no network events were observed (e.g. pages served from cache). The idle timer is now only satisfied after a consistent **500 ms idle period** has elapsed, preventing false-positive idle detection. The core polling logic has also been extracted into a standalone `poll_network_idle` function to improve testability (#847)\n\n## 0.20.12\n\n### Patch Changes\n\n- 5fa2396: ### Bug Fixes\n\n - Fixed **`snapshot -C`** and **`screenshot --annotate`** hanging when connected over WSS (WebSocket Secure) due to sequential CDP round-trips per interactive element (#842)\n\n ### Performance\n\n - **`snapshot -C` (cursor-interactive mode)** now batches CDP calls instead of issuing N×2 sequential round-trips per cursor-interactive element, preventing timeouts on high-latency WSS connections (#842)\n - **`screenshot --annotate`** now batches element queries, reducing completion time from potentially 20–40s (e.g. 50+ buttons over WSS) to within expected bounds (#842)\n\n## 0.20.11\n\n### Patch Changes\n\n- 4b5fc78: ### Bug Fixes\n\n - **Material Design checkbox/radio parity** - Restored Playwright-parity behavior for `check`/`uncheck` actions on Material Design controls. These components hide the native `` off-screen and use overlay elements that intercept coordinate-based clicks; the actions now detect this pattern and fall back to a JS `.click()` to correctly toggle state. Also improves `ischecked` to handle nested hidden inputs and ARIA-only checkboxes (#837)\n - **Punctuation handling in `type` command** - Fixed incorrect virtual key (VK) codes being used for punctuation characters (e.g. `.`, `@`) in the `type` action, which previously caused those characters to be dropped or mistyped (#836)\n\n## 0.20.10\n\n### Patch Changes\n\n- a3d9662: ### Bug Fixes\n\n - **Restored WebSocket streaming** - Fixed broken WebSocket streaming in the native daemon by keeping the **StreamServer** instance alive so the broadcast channel remains open, and ensuring CDP session IDs and connection status are correctly propagated to stream clients (#826)\n - **Filtered internal Chrome targets** - Fixed auto-connect discovery incorrectly attempting to attach to Chrome-internal pages (e.g. `chrome://`, `chrome-extension://`, `devtools://` URLs), which could cause unexpected connection failures (#827)\n\n## 0.20.9\n\n### Patch Changes\n\n- 51d9ab4: ### Bug Fixes\n\n - **Appium v3 iOS capabilities** - Added `appium:` vendor prefix to iOS capabilities (e.g., `appium:automationName`, `appium:deviceName`, `appium:platformVersion`) to comply with the Appium v3 WebDriver protocol requirements (#810)\n - **Snapshot `--selector` scoping** - Fixed `snapshot --selector` so that the output is properly scoped to the matched element's subtree rather than returning the full accessibility tree. The selector now resolves the target DOM node's backend IDs and filters the accessibility tree to only include nodes within that subtree (#825)\n\n## 0.20.8\n\n### Patch Changes\n\n- daf7263: ### Bug Fixes\n\n - Fixed **video duration** being reported incorrectly when using real-time ffmpeg encoding for screen recording (#812)\n - Removed obsolete **`BrowserManager` TypeScript API** references that no longer reflect the current CLI-based usage model (#821)\n\n ### Documentation\n\n - Updated README to replace outdated **`BrowserManager` programmatic API** examples with the current CLI-based approach using `execSync` and `agent-browser` commands (#821)\n - Removed the **Programmatic API** section covering `BrowserManager` screencast and input injection methods, which are no longer part of the public API (#821)\n\n## 0.20.7\n\n### Patch Changes\n\n- 25a1526: ### New Features\n\n - **Brave Browser support** - Added auto-discovery of Brave Browser for CDP connections on macOS, Linux, and Windows. The agent will now automatically detect and connect to Brave alongside Chrome, Chromium, and Canary installations (#817)\n\n ### Improvements\n\n - **Postinstall message** - The post-install message now detects existing Chrome installations on the system. If a compatible browser is found, it confirms the path and notes it will be used automatically instead of prompting an install. If no browser is detected, the warning is clearer and mentions that installation can be skipped when using `--cdp`, `--provider`, `--engine`, or `--executable-path` (#815)\n\n## 0.20.6\n\n### Patch Changes\n\n- fa91c22: ### Bug Fixes\n\n - **Stale accessibility tree reference fallback** - Fixed an issue where interacting with an element whose **`backend_node_id`** had become stale (e.g. after the DOM was replaced) would fail with a `Could not compute box model` CDP error. Element resolution now re-queries the accessibility tree using role/name lookup to obtain a fresh node ID before retrying the operation (#806)\n\n## 0.20.5\n\n### Patch Changes\n\n- fc091d2: ### Bug Fixes\n\n - **Daemon panic on broken stderr pipe** - Replaced all `eprintln!` calls with `writeln!(std::io::stderr(), ...)` wrapped in `let _ =` to silently discard write errors, preventing the daemon from panicking when the parent process drops the stderr pipe during Chrome launch (#802)\n\n## 0.20.4\n\n### Patch Changes\n\n- e2ebde2: ### Bug Fixes\n\n - **Broadcast channel lag handling** - Fixed an issue where **broadcast channel lag** errors were incorrectly treated as stream closure, causing premature termination of event listeners in reload, response body, download, and navigation wait operations. Lagged messages are now skipped and the loop continues instead of breaking (#797)\n\n ### Improvements\n\n - Removed unused **pnpm setup** steps from the `global-install` CI job, simplifying the workflow configuration (#798)\n\n## 0.20.3\n\n### Patch Changes\n\n- e365909: ### Bug Fixes\n\n - **Chrome launch retry** - Chrome will now retry launching up to 3 times with a 500ms delay between attempts, improving resilience against transient startup failures (#791)\n - **Remote CDP snapshot hang** - Resolved an issue where snapshots would hang indefinitely over remote CDP (WSS) connections by removing WebSocket message and frame size limits to accommodate large responses (e.g. `Accessibility.getFullAXTree`), accepting binary frames from remote proxies such as Browserless, and immediately clearing pending commands when the connection closes rather than waiting for the 30-second timeout (#792)\n\n## 0.20.2\n\n### Patch Changes\n\n- 944fa01: ### New Features\n\n - **Linux musl (Alpine) builds** - Added pre-built binaries for **linux-musl** targeting both **x64** and **arm64** architectures, enabling native support for Alpine Linux and other musl-based distributions without requiring glibc (#784)\n\n ### Improvements\n\n - **Consecutive `--auto-connect` commands** - Added support for issuing multiple consecutive `--auto-connect` commands without requiring a full browser relaunch; external connections are now correctly identified and reused (#786)\n - **External browser disconnect behavior** - When using `--auto-connect` or `--cdp`, closing the agent session now disconnects cleanly without shutting down the user's browser process\n\n ### Bug Fixes\n\n - **Restored `refs` dict in `--json` snapshot output** - The `refs` map containing role and name metadata for referenced elements is now correctly included in JSON snapshot responses (#787)\n - Fixed e2e test assertions for `diff_snapshot` and `domain_filter` to correctly reflect expected behavior (#783)\n - Fixed Chrome temp-dir cleanup test failing on Windows (#766)\n\n## 0.20.1\n\n### Patch Changes\n\n- bd05917: ### Bug Fixes\n\n - Fixed **AX tree deserialization** to accept integer `nodeId` and `childIds` values for compatibility with Lightpanda, which sends numeric IDs where Chrome sends strings (#775)\n - Fixed **misleading SIGPIPE comment** to accurately describe the default Rust SIGPIPE behavior and why it is reset to `SIG_DFL` (#776)\n - Fixed **WebM recording output** to use the VP9 codec (`libvpx-vp9`) instead of H.264, producing valid WebM files; also adds a padding filter to ensure even frame dimensions (#779)\n\n## 0.20.0\n\n### Minor Changes\n\n- 235fa88: ### Full Native Rust\n\n - **100% native Rust** -- Removed the entire Node.js/Playwright daemon. The Rust native daemon is now the only implementation. No Node.js runtime or Playwright dependency required. (#754)\n - **99x smaller install** -- Install size reduced from 710 MB to 7 MB by eliminating the Node.js dependency tree.\n - **18x less memory** -- Daemon memory usage reduced from 143 MB to 8 MB.\n - **1.6x faster cold start** -- Cold start time reduced from 1002ms to 617ms.\n - **Benchmarks** -- Added benchmark suite comparing native vs Node.js daemon performance.\n - **Chromium installer hardened** -- Fixed zip path traversal vulnerability in Chrome for Testing installer.\n\n ### Bug Fixes\n\n - Fixed `--headed false` flag not being respected in CLI (#757)\n - Fixed \"not found\" error pattern in `to_ai_friendly_error` incorrectly catching non-element errors (#759)\n - Fixed storage local key lookup parsing and text output (#761)\n - Fixed Lightpanda engine launch with release binaries (#760)\n - Hardened Lightpanda startup timeouts (#762)\n\n## 0.19.0\n\n### Minor Changes\n\n- 56bb92b: ### New Features\n\n - **Browserless.io provider** -- Added browserless.io as a browser provider, supported in both Node.js and native daemon paths. Connect to remote Browserless instances with `--provider browserless` or `AGENT_BROWSER_PROVIDER=browserless`. Configurable via `BROWSERLESS_API_KEY`, `BROWSERLESS_API_URL`, and `BROWSERLESS_BROWSER_TYPE` environment variables. (#502, #746)\n - **`clipboard` command** -- Read from and write to the browser clipboard. Supports `read`, `write `, `copy` (simulates Ctrl+C), and `paste` (simulates Ctrl+V) operations. (#749)\n - **Screenshot output configuration** -- New global flags `--screenshot-dir`, `--screenshot-quality`, `--screenshot-format` and corresponding `AGENT_BROWSER_SCREENSHOT_DIR`, `AGENT_BROWSER_SCREENSHOT_QUALITY`, `AGENT_BROWSER_SCREENSHOT_FORMAT` environment variables for persistent screenshot settings. (#749)\n\n ### Bug Fixes\n\n - Fixed `wait --text` not working in native daemon path (#749)\n - Fixed `BrowserManager.navigate()` and package entry point (#748)\n - Fixed extensions not being loaded from `config.json` (#750)\n - Fixed scroll on page load (#747)\n - Fixed HTML retrieval by using `browser.getLocator()` for selector operations (#745)\n\n## 0.18.0\n\n### Minor Changes\n\n- 942b8cd: ### New Features\n\n - **`inspect` command** - Opens Chrome DevTools for the active page by launching a local proxy server that forwards the DevTools frontend to the browser's CDP WebSocket. Commands continue to work while DevTools is open. Implemented in both Node.js and native paths. (#736)\n - **`get cdp-url` subcommand** - Retrieve the Chrome DevTools Protocol WebSocket URL for the active page, useful for external debugging tools. (#736)\n - **Native screenshot annotate** - The `--annotate` flag for screenshots now works in the native Rust daemon, bringing parity with the Node.js path. (#706)\n\n ### Improvements\n\n - **KERNEL_API_KEY now optional** - External credential injection no longer requires `KERNEL_API_KEY` to be set, making it easier to use Kernel with pre-configured environments. (#687)\n - **Browserbase simplified** - Removed the `BROWSERBASE_PROJECT_ID` requirement, reducing setup friction for Browserbase users. (#625)\n\n ### Bug Fixes\n\n - Fixed Browserbase API using incorrect endpoint to release sessions (#707)\n - Fixed CDP connect paths using hardcoded 10s timeout instead of `getDefaultTimeout()` (#704)\n - Fixed lone Unicode surrogates causing errors by sanitizing with `toWellFormed()` (#720)\n - Fixed CDP connection failure on IPv6-first systems (#717)\n - Fixed recordings not inheriting the current viewport settings (#718)\n\n## 0.17.1\n\n### Patch Changes\n\n- 94cd888: Added support for device scale factor (retina display) in the viewport command via an optional scale parameter. Also added webview target type support for better Electron application compatibility, and the pages list now includes target type information.\n\n## 0.17.0\n\n### Minor Changes\n\n- 94521e7: ### New Features\n\n - **Lightpanda browser engine support** - Added `--engine ` flag to select the browser engine (`chrome` by default, or `lightpanda`), implying `--native` mode. Configurable via `AGENT_BROWSER_ENGINE` environment variable (#646)\n - **Dialog dismiss command** - Added support for `dismiss` subcommand in dialog command parsing (#605)\n\n ### Improvements\n\n - **Daemon startup error reporting** - Daemon startup errors are now surfaced directly instead of showing an opaque timeout message (#614)\n - **CDP port discovery** - Replaced broken hand-rolled HTTP client with `reqwest` for more reliable CDP port discovery (#619)\n - **Chrome extensions** - Extensions now load correctly by forcing headed mode when extensions are present (#652)\n - **Google Translate bar suppression** - Suppressed the Google Translate bar in native headless mode to avoid interference (#649)\n - **Auth cookie persistence** - Auth cookies are now persisted on browser close in native mode (#650)\n\n ### Bug Fixes\n\n - Fixed native auth login failing due to incompatible encryption format (#648)\n\n ### Documentation\n\n - Improved snapshot usage guidance and added reproducibility check (#630)\n - Added `--engine` flag to the README options table\n\n ### Performance\n\n - Added benchmarks to the CLI codebase (#637)\n\n## 0.16.3\n\n### Patch Changes\n\n- 7d2c895: Fixed an issue where the --native flag was being passed to child processes even when not explicitly specified on the command line. The flag is now only forwarded when the user explicitly provides it, consistent with how other CLI flags like --allow-file-access and --download-path are handled.\n\n## 0.16.2\n\n### Patch Changes\n\n- 01ac557: Added AGENT_BROWSER_HEADED environment variable support for running the browser in headed mode, and improved temporary profile cleanup when launching Chrome directly. Also includes documentation clarification that browser extensions work in both headed and headless modes.\n\n## 0.16.1\n\n### Patch Changes\n\n- c4180c8: Improved Chrome launch reliability by automatically detecting containerized environments (Docker, Podman, Kubernetes) and enabling --no-sandbox when needed. Added support for discovering Playwright-installed Chromium browsers and enhanced error messages with helpful diagnostics when Chrome fails to launch.\n\n## 0.16.0\n\n### Minor Changes\n\n- 05018b3: Added experimental native Rust daemon (`--native` flag, `AGENT_BROWSER_NATIVE=1` env, or `\"native\": true` in config). The native daemon communicates with Chrome directly via CDP, eliminating Node.js and Playwright dependencies. Supports 150+ commands with full parity to the default Node.js daemon. Includes WebDriver backend for Safari/iOS, CDP protocol codegen, request tracking, frame context management, and comprehensive e2e and parity tests.\n\n## 0.15.3\n\n### Patch Changes\n\n- 62241b5: Fixed Windows compatibility issues including proper handling of extended-length path prefixes from canonicalize(), prevention of MSYS/Git Bash path translation that could mangle arguments, and improved daemon startup reliability. Also added ARM64 Windows support in postinstall shims and expanded CI testing with a full daemon lifecycle test on Windows.\n\n## 0.15.2\n\n### Patch Changes\n\n- 6aea316: Documentation site improvements and internal tooling updates including enhanced code blocks, mobile navigation, and docs chat components. CLI connection and output handling refinements. Skill creator reference documentation and scripts have been reorganized.\n\n## 0.15.1\n\n### Patch Changes\n\n- 7bd8ce9: Added support for chrome:// and chrome-extension:// URLs in navigation and recording commands. These special browser URLs are now preserved as-is instead of having https:// incorrectly prepended.\n\n## 0.15.0\n\n### Minor Changes\n\n- 2e38882: - Added security hardening: authentication vault, content boundary markers, domain allowlist, action policy, action confirmation, and output length limits.\n - Added `--download-path` flag (and `AGENT_BROWSER_DOWNLOAD_PATH` env / `downloadPath` config key) to set a default download directory.\n - Added `--selector` flag to `scroll` command for scrolling within specific container elements.\n\n## 0.14.0\n\n### Minor Changes\n\n- b7665e5: - Added `keyboard` command for raw keyboard input -- type with real keystrokes, insert text, and press shortcuts at the currently focused element without needing a selector.\n - Added `--color-scheme` flag and `AGENT_BROWSER_COLOR_SCHEME` env var for persistent dark/light mode preference across browser sessions.\n - Fixed IPC EAGAIN errors (os error 35/11) by adding backpressure-aware socket writes, command serialization, and lowering the default Playwright timeout to 25s (configurable via `AGENT_BROWSER_DEFAULT_TIMEOUT`).\n - Fixed remote debugging (CDP) reconnection.\n - Fixed state load failing when no browser is running.\n - Fixed `--annotate` flag warning appearing when not explicitly passed via CLI.\n\n## 0.13.0\n\n### Minor Changes\n\n- ebd8717: Added new diff commands for comparing snapshots, screenshots, and URLs between page states. You can now run visual pixel diffs against baseline images, compare accessibility tree snapshots with customizable depth and selectors, and diff two URLs side-by-side with optional screenshot comparison.\n\n## 0.12.0\n\n### Minor Changes\n\n- 69ffad0: Add annotated screenshots with the new --annotate flag, which overlays numbered labels on interactive elements and prints a legend mapping each label to its element ref. This enables multimodal AI models to reason about visual layout while using the same @eN refs for subsequent interactions. The flag can also be set via the AGENT_BROWSER_ANNOTATE environment variable.\n\n## 0.11.1\n\n### Patch Changes\n\n- c6fc7df: Added documentation for command chaining with && across README, CLI help output, docs, and skill files, explaining how to efficiently chain multiple agent-browser commands in a single shell invocation since the browser persists via a background daemon.\n\n## 0.11.0\n\n### Minor Changes\n\n- 5dc40b4: Added configuration file support with automatic loading from user and project directories, new profiler commands for Chrome DevTools profiling, computed styles getter, browser extension loading, storage state management, and iOS device emulation. Expanded click command with new-tab option, improved find command with additional actions and filtering options, and enhanced CDP connection to accept WebSocket URLs. Documentation has been significantly expanded with new sections for configuration, profiling, and proxy support.\n\n## 0.10.0\n\n### Minor Changes\n\n- 1112a16: Added session persistence with automatic save/restore of cookies and localStorage across browser restarts using --session-name flag, with optional AES-256-GCM encryption for saved state data. New state management commands allow listing, showing, renaming, clearing, and cleaning up old session files. Also added --new-tab option for click commands to open links in new tabs.\n\n## 0.9.4\n\n### Patch Changes\n\n- 323b6cd: Fix all Clippy lint warnings in the Rust CLI: remove redundant import, use `.first()` instead of `.get(0)`, use `.copied()` instead of `.map(|s| *s)`, use `.contains()` instead of `.iter().any()`, use `then_some` instead of lazy `then`, and simplify redundant match guards.\n\n## 0.9.3\n\n### Patch Changes\n\n- d03e238: Added support for custom executable path in CLI browser launch options. Documentation site received UI improvements including a new chat component with sheet-based interface and updated dependencies.\n\n## 0.9.2\n\n### Patch Changes\n\n- 76d23db: Documentation site migrated to MDX for improved content authoring, added AI-powered docs chat feature, and updated README with Homebrew installation instructions for macOS users.\n\n## 0.9.1\n\n### Patch Changes\n\n- ae34945: Added --allow-file-access flag to enable opening and interacting with local file:// URLs (PDFs, HTML files) by passing Chromium flags that allow JavaScript access to local files. Added -C/--cursor flag for snapshots to include cursor-interactive elements like divs with onclick handlers or cursor:pointer styles, which is useful for modern web apps using custom clickable elements.\n\n## 0.9.0\n\n### Minor Changes\n\n- 9d021bd: Add iOS Simulator and real device support for mobile Safari testing via Appium. New CLI commands include `device list` to show available simulators, `tap` and `swipe` for touch interactions, and the `--device` flag to specify which iOS device to use. Configure with `-p ios` provider flag or `AGENT_BROWSER_PROVIDER=ios` environment variable.\n\n## 0.8.10\n\n### Patch Changes\n\n- 17dba8f: Add --stdin flag for eval command to read JavaScript from stdin, enabling heredoc usage for multiline scripts\n- daeede4: Add --stdin flag for the eval command to read JavaScript from stdin, enabling heredoc usage for multiline scripts. Also fix binary permission issues on macOS/Linux when postinstall scripts don't run (e.g., with bun).\n\n## 0.8.9\n\n### Patch Changes\n\n- 0dc36f2: Add --stdin flag for eval command to read JavaScript from stdin, enabling heredoc usage for multiline scripts\n\n## 0.8.8\n\n### Patch Changes\n\n- 2771588: Added base64 encoding support for the eval command with -b/--base64 flag to avoid shell escaping issues when executing JavaScript. Updated documentation with AI agent setup instructions and reorganized the docs structure by consolidating agent mode content into the installation page.\n\n## 0.8.7\n\n### Patch Changes\n\n- d24f753: Fixed browser launch options not being passed correctly when using persistent profiles, ensuring args, userAgent, proxy, and ignoreHTTPSErrors settings now work properly. Added pre-flight checks for socket path length limits and directory write permissions to provide clearer error messages when daemon startup fails. Improved error handling to properly exit with failure status when browser launch fails.\n\n## 0.8.6\n\n### Patch Changes\n\n- d75350a: Improved daemon connection reliability by adding automatic retry logic for transient errors like connection resets, broken pipes, and temporary resource unavailability. The CLI now cleans up stale socket and PID files before starting a new daemon, and includes better detection of daemon responsiveness to handle race conditions during shutdown.\n\n## 0.8.5\n\n### Patch Changes\n\n- cb2f8c3: Fixed version synchronization to automatically update Cargo.lock alongside Cargo.toml during releases, and made the CLI binary executable. This ensures the Rust CLI version stays in sync with the npm package version.\n\n## 0.8.4\n\n### Patch Changes\n\n- 759302e: Fixed \"Daemon not found\" error when running through AI agents (e.g., Claude Code) by resolving symlinks in the executable path. Previously, npm global bin symlinks weren't being resolved correctly, causing intermittent daemon discovery failures.\n\n## 0.8.3\n\n### Patch Changes\n\n- 4116a8a: Replaced shell-based CLI wrappers with a cross-platform Node.js wrapper to enable npx support on Windows. Added postinstall logic to patch npm's bin entry on global installs, allowing the native binary to be invoked directly with zero overhead. Added CI tests to verify global installation works correctly across all platforms.\n\n## 0.8.2\n\n### Patch Changes\n\n- 7e6336f: Fixed the Windows CMD wrapper to use the native binary directly instead of routing through Node.js, improving startup performance and reliability. Added retry logic to the CI install command to handle transient failures during browser installation.\n\n## 0.8.1\n\n### Patch Changes\n\n- 8eec634: Improved release workflow to validate binary file sizes and ensure binaries are executable after npm install. Updated documentation site with a new mobile navigation system and added v0.8.0 changelog entries. Reformatted CHANGELOG.md for better readability.\n\n## v0.8.0\n\n### New Features\n\n- **Kernel cloud browser provider** - Connect to Kernel (https://kernel.sh) for remote browser infrastructure via `-p kernel` flag or `AGENT_BROWSER_PROVIDER=kernel`. Supports stealth mode, persistent profiles, and automatic profile find-or-create.\n- **Ignore HTTPS certificate errors** - New `--ignore-https-errors` flag for working with self-signed certificates and development environments\n- **Enhanced cookie management** - Extended `cookies set` command with `--url`, `--domain`, `--path`, `--httpOnly`, `--secure`, `--sameSite`, and `--expires` flags for setting cookies before page load\n\n### Bug Fixes\n\n- Fixed tab list command not recognizing new pages opened via clicks or `target=\"_blank\"` links (#275)\n- Fixed `check` command hanging indefinitely (#272)\n- Fixed `set device` not applying deviceScaleFactor - HiDPI screenshots now work correctly (#270)\n- Fixed state load and profile persistence not working in v0.7.6 (#268)\n- Screenshots now save to temp directory when no path is provided (#247)\n\n### Security\n\n- Daemon and stream server now reject cross-origin connections (#274)\n\n## 0.7.6\n\n### Patch Changes\n\n- a4d0c26: Allow null values for the screenshot selector field. Previously, passing a null selector would fail validation, but now it is properly handled as an optional value.\n\n## 0.7.5\n\n### Patch Changes\n\n- 8c2a6ec: Fix GitHub release workflow to handle existing releases. If a release already exists, binaries are uploaded to it instead of failing.\n\n## 0.7.4\n\n### Patch Changes\n\n- 957b5e5: Fix binary permissions on install. npm doesn't preserve execute bits, so postinstall now ensures the native binary is executable.\n\n## 0.7.3\n\n### Patch Changes\n\n- 161d8f5: Fix native binary distribution in npm package. Native binaries for all platforms (Linux x64/arm64, macOS x64/arm64, Windows x64) are now correctly included when publishing.\n\n## 0.7.2\n\n### Patch Changes\n\n- 6afede2: Fix native binary distribution in npm package\n\n Native binaries for all platforms (Linux x64/arm64, macOS x64/arm64, Windows x64) are now included in the npm package. Previously, the release workflow published to npm before building binaries, causing \"No binary found\" errors on installation.\n\n## 0.7.1\n\n### Patch Changes\n\n- Fix native binary distribution in npm package. Native binaries for all platforms (Linux x64/arm64, macOS x64/arm64, Windows x64) are now included in the npm package. Previously, the release workflow published to npm before building binaries, causing \"No binary found\" errors on installation.\n\n## 0.7.0\n\n### Minor Changes\n\n- 316e649: ## New Features\n\n - **Cloud browser providers** - Connect to Browserbase or Browser Use for remote browser infrastructure via `-p` flag or `AGENT_BROWSER_PROVIDER` env var\n - **Persistent browser profiles** - Store cookies, localStorage, and login sessions across browser restarts with `--profile`\n - **Remote CDP WebSocket URLs** - Connect to remote browser services via WebSocket URL (e.g., `--cdp \"wss://...\"`)\n - **Download commands** - New `download` command and `wait --download` for file downloads with ref support\n - **Browser launch configuration** - New `--args`, `--user-agent`, and `--proxy-bypass` flags for fine-grained browser control\n - **Enhanced skills** - Hierarchical structure with references and templates for Claude Code\n\n ## Bug Fixes\n\n - Screenshot command now supports refs and has improved error messages\n - WebSocket URLs work in `connect` command\n - Fixed socket file location (uses `~/.agent-browser` instead of TMPDIR)\n - Windows binary path fix (.exe extension)\n - State load and path-based actions now show correct output messages\n\n ## Documentation\n\n - Added Claude Code marketplace plugin installation instructions\n - Updated skill documentation with references and templates\n - Improved error documentation\n" }, { "path": "LICENSE", "content": " Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nAPPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\nCopyright 2025 Vercel Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n" }, { "path": "README.md", "content": "# agent-browser\n\nHeadless browser automation CLI for AI agents. Fast native Rust CLI.\n\n## Installation\n\n### Global Installation (recommended)\n\nInstalls the native Rust binary:\n\n```bash\nnpm install -g agent-browser\nagent-browser install # Download Chrome from Chrome for Testing (first time only)\n```\n\n### Project Installation (local dependency)\n\nFor projects that want to pin the version in `package.json`:\n\n```bash\nnpm install agent-browser\nagent-browser install\n```\n\nThen use via `package.json` scripts or by invoking `agent-browser` directly.\n\n### Homebrew (macOS)\n\n```bash\nbrew install agent-browser\nagent-browser install # Download Chrome from Chrome for Testing (first time only)\n```\n\n### Cargo (Rust)\n\n```bash\ncargo install agent-browser\nagent-browser install # Download Chrome from Chrome for Testing (first time only)\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/vercel-labs/agent-browser\ncd agent-browser\npnpm install\npnpm build\npnpm build:native # Requires Rust (https://rustup.rs)\npnpm link --global # Makes agent-browser available globally\nagent-browser install\n```\n\n### Linux Dependencies\n\nOn Linux, install system dependencies:\n\n```bash\nagent-browser install --with-deps\n```\n\n### Updating\n\nUpgrade to the latest version:\n\n```bash\nagent-browser upgrade\n```\n\nDetects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command automatically.\n\n### Requirements\n\n- **Chrome** - Run `agent-browser install` to download Chrome from [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing/) (Google's official automation channel). No Playwright or Node.js required for the daemon.\n- **Rust** - Only needed when building from source (see From Source above).\n\n## Quick Start\n\n```bash\nagent-browser open example.com\nagent-browser snapshot # Get accessibility tree with refs\nagent-browser click @e2 # Click by ref from snapshot\nagent-browser fill @e3 \"test@example.com\" # Fill by ref\nagent-browser get text @e1 # Get text by ref\nagent-browser screenshot page.png\nagent-browser close\n```\n\n### Traditional Selectors (also supported)\n\n```bash\nagent-browser click \"#submit\"\nagent-browser fill \"#email\" \"test@example.com\"\nagent-browser find role button click --name \"Submit\"\n```\n\n## Commands\n\n### Core Commands\n\n```bash\nagent-browser open # Navigate to URL (aliases: goto, navigate)\nagent-browser click # Click element (--new-tab to open in new tab)\nagent-browser dblclick # Double-click element\nagent-browser focus # Focus element\nagent-browser type # Type into element\nagent-browser fill # Clear and fill\nagent-browser press # Press key (Enter, Tab, Control+a) (alias: key)\nagent-browser keyboard type # Type with real keystrokes (no selector, current focus)\nagent-browser keyboard inserttext # Insert text without key events (no selector)\nagent-browser keydown # Hold key down\nagent-browser keyup # Release key\nagent-browser hover # Hover element\nagent-browser select # Select dropdown option\nagent-browser check # Check checkbox\nagent-browser uncheck # Uncheck checkbox\nagent-browser scroll [px] # Scroll (up/down/left/right, --selector )\nagent-browser scrollintoview # Scroll element into view (alias: scrollinto)\nagent-browser drag # Drag and drop\nagent-browser upload # Upload files\nagent-browser screenshot [path] # Take screenshot (--full for full page, saves to a temporary directory if no path)\nagent-browser screenshot --annotate # Annotated screenshot with numbered element labels\nagent-browser screenshot --screenshot-dir ./shots # Save to custom directory\nagent-browser screenshot --screenshot-format jpeg --screenshot-quality 80\nagent-browser pdf # Save as PDF\nagent-browser snapshot # Accessibility tree with refs (best for AI)\nagent-browser eval # Run JavaScript (-b for base64, --stdin for piped input)\nagent-browser connect # Connect to browser via CDP\nagent-browser close # Close browser (aliases: quit, exit)\n```\n\n### Get Info\n\n```bash\nagent-browser get text # Get text content\nagent-browser get html # Get innerHTML\nagent-browser get value # Get input value\nagent-browser get attr # Get attribute\nagent-browser get title # Get page title\nagent-browser get url # Get current URL\nagent-browser get cdp-url # Get CDP WebSocket URL (for DevTools, debugging)\nagent-browser get count # Count matching elements\nagent-browser get box # Get bounding box\nagent-browser get styles # Get computed styles\n```\n\n### Check State\n\n```bash\nagent-browser is visible # Check if visible\nagent-browser is enabled # Check if enabled\nagent-browser is checked # Check if checked\n```\n\n### Find Elements (Semantic Locators)\n\n```bash\nagent-browser find role [value] # By ARIA role\nagent-browser find text # By text content\nagent-browser find label