diff --git a/README.md b/README.md index cc50e9c..5c913ec 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,43 @@ Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallba ## Installation -### npm (recommended) +### Global Installation (recommended) + +Installs the native Rust binary for maximum performance: ```bash npm install -g agent-browser agent-browser install # Download Chromium ``` +This is the fastest option -- commands run through the native Rust CLI directly with sub-millisecond parsing overhead. + +### Quick Start (no install) + +Run directly with `npx` if you want to try it without installing globally: + +```bash +npx agent-browser install # Download Chromium (first time only) +npx agent-browser open example.com +``` + +> **Note:** `npx` routes through Node.js before reaching the Rust CLI, so it is noticeably slower than a global install. For regular use, install globally. + +### Project Installation (local dependency) + +For projects that want to pin the version in `package.json`: + +```bash +npm install agent-browser +npx agent-browser install +``` + +Then use via `npx` or `package.json` scripts: + +```bash +npx agent-browser open example.com +``` + ### Homebrew (macOS) ```bash @@ -752,7 +782,7 @@ The daemon starts automatically on first command and persists between commands f ### Just ask the agent -The simplest approach - just tell your agent to use it: +The simplest approach -- just tell your agent to use it: ``` Use agent-browser to test the login flow. Run agent-browser --help to see available commands. @@ -760,7 +790,7 @@ Use agent-browser to test the login flow. Run agent-browser --help to see availa The `--help` output is comprehensive and most agents can figure it out from there. -### AI Coding Assistants +### AI Coding Assistants (recommended) Add the skill to your AI coding assistant for richer context: @@ -768,7 +798,17 @@ Add the skill to your AI coding assistant for richer context: npx skills add vercel-labs/agent-browser ``` -This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf. +This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf. The skill is fetched from the repository, so it stays up to date automatically -- do not copy `SKILL.md` from `node_modules` as it will become stale. + +### Claude Code + +Install as a Claude Code skill: + +```bash +npx skills add vercel-labs/agent-browser +``` + +This adds the skill to `.claude/skills/agent-browser/SKILL.md` in your project. The skill teaches Claude Code the full agent-browser workflow, including the snapshot-ref interaction pattern, session management, and timeout handling. ### AGENTS.md / CLAUDE.md diff --git a/cli/src/output.rs b/cli/src/output.rs index 7f083a5..f9fa3c2 100644 --- a/cli/src/output.rs +++ b/cli/src/output.rs @@ -1888,6 +1888,13 @@ Environment: AGENT_BROWSER_IOS_DEVICE Default iOS device name AGENT_BROWSER_IOS_UDID Default iOS device UDID +Install (recommended, fastest - native Rust CLI): + npm install -g agent-browser + agent-browser install # Download Chromium (first time) + +Try without installing (slower, routes through Node.js): + npx agent-browser open example.com + Examples: agent-browser open example.com agent-browser snapshot -i # Interactive elements only @@ -1896,6 +1903,7 @@ Examples: agent-browser find role button click --name Submit agent-browser get text @e1 agent-browser screenshot --full + agent-browser wait --load networkidle # Wait for slow pages to load agent-browser --cdp 9222 snapshot # Connect via CDP port agent-browser --auto-connect snapshot # Auto-discover running Chrome agent-browser --profile ~/.myapp open example.com # Persistent profile diff --git a/docs/src/app/installation/page.mdx b/docs/src/app/installation/page.mdx index 4ed7c7d..fe0fbb9 100644 --- a/docs/src/app/installation/page.mdx +++ b/docs/src/app/installation/page.mdx @@ -2,13 +2,43 @@ export const metadata = { title: "Installation" } # Installation -## npm (recommended) +## Global installation (recommended) + +Installs the native Rust binary for maximum performance: ```bash npm install -g agent-browser agent-browser install # Download Chromium ``` +This is the fastest option -- commands run through the native Rust CLI directly with sub-millisecond parsing overhead. + +## Quick start (no install) + +Run directly with `npx` if you want to try it without installing globally: + +```bash +npx agent-browser install # Download Chromium (first time only) +npx agent-browser open example.com +``` + +> **Note:** `npx` routes through Node.js before reaching the Rust CLI, so it is noticeably slower than a global install. For regular use, install globally. + +## Project installation (local dependency) + +For projects that want to pin the version in `package.json`: + +```bash +npm install agent-browser +npx agent-browser install +``` + +Then use via `npx` or `package.json` scripts: + +```bash +npx agent-browser open example.com +``` + ## Homebrew (macOS) ```bash @@ -73,6 +103,18 @@ export async function handler() { agent-browser works with any AI agent out of the box. For richer context: +### AI coding assistants (recommended) + +Install the skill for your AI coding assistant: + +```bash +npx skills add vercel-labs/agent-browser +``` + +This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf. The skill is fetched from the repository and stays up to date automatically. + +> **Do not** copy `SKILL.md` from `node_modules` -- it will become stale as new features are added. Always use `npx skills add` or reference the repository version. + ### AGENTS.md / CLAUDE.md Add to your instructions file: @@ -88,17 +130,3 @@ Core workflow: 3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs 4. Re-snapshot after page changes ``` - -### Claude Code skill - -```bash -cp -r node_modules/agent-browser/skills/agent-browser .claude/skills/ -``` - -Or download: - -```bash -mkdir -p .claude/skills/agent-browser -curl -o .claude/skills/agent-browser/SKILL.md \ - https://raw.githubusercontent.com/vercel-labs/agent-browser/main/skills/agent-browser/SKILL.md -``` diff --git a/docs/src/app/page.mdx b/docs/src/app/page.mdx index 3497322..962c6d2 100644 --- a/docs/src/app/page.mdx +++ b/docs/src/app/page.mdx @@ -5,8 +5,11 @@ export const metadata = { title: "agent-browser" } Browser automation CLI designed for AI agents. Compact text output minimizes context usage. Fast Rust CLI with Node.js fallback. ```bash -npm install -g agent-browser # all platforms +npm install -g agent-browser # all platforms (fastest, native Rust CLI) brew install agent-browser # macOS + +# or try without installing +npx agent-browser open example.com ``` ## Features diff --git a/skills/agent-browser/SKILL.md b/skills/agent-browser/SKILL.md index 4eea651..c68fb09 100644 --- a/skills/agent-browser/SKILL.md +++ b/skills/agent-browser/SKILL.md @@ -1,7 +1,7 @@ --- name: agent-browser description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. -allowed-tools: Bash(agent-browser:*) +allowed-tools: Bash(npx agent-browser:*), Bash(agent-browser:*) --- # Browser Automation with agent-browser @@ -198,6 +198,52 @@ agent-browser -p ios close **Real devices:** Works with physical iOS devices if pre-configured. Use `--device ""` where UDID is from `xcrun xctrace list devices`. +## Timeouts and Slow Pages + +The default Playwright timeout is 60 seconds for local browsers. For slow websites or large pages, use explicit waits instead of relying on the default timeout: + +```bash +# Wait for network activity to settle (best for slow pages) +agent-browser wait --load networkidle + +# Wait for a specific element to appear +agent-browser wait "#content" +agent-browser wait @e1 + +# Wait for a specific URL pattern (useful after redirects) +agent-browser wait --url "**/dashboard" + +# Wait for a JavaScript condition +agent-browser wait --fn "document.readyState === 'complete'" + +# Wait a fixed duration (milliseconds) as a last resort +agent-browser wait 5000 +``` + +When dealing with consistently slow websites, use `wait --load networkidle` after `open` to ensure the page is fully loaded before taking a snapshot. If a specific element is slow to render, wait for it directly with `wait ` or `wait @ref`. + +## Session Management and Cleanup + +When running multiple agents or automations concurrently, always use named sessions to avoid conflicts: + +```bash +# Each agent gets its own isolated session +agent-browser --session agent1 open site-a.com +agent-browser --session agent2 open site-b.com + +# Check active sessions +agent-browser session list +``` + +Always close your browser session when done to avoid leaked processes: + +```bash +agent-browser close # Close default session +agent-browser --session agent1 close # Close specific session +``` + +If a previous session was not closed properly, the daemon may still be running. Use `agent-browser close` to clean it up before starting new work. + ## Ref Lifecycle (Important) Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after: