| name | agent-browser |
| version | 1.3.0 |
| description | Use this skill when the user needs browser automation, including opening web pages, taking screenshots, extracting page content, clicking elements, filling forms, or testing web flows. This skill uses the open source vercel-labs/agent-browser CLI and supports macOS, Linux, and Windows x64. |
Agent Browser
Use agent-browser CLI for full browser automation tasks. It is suitable when a page needs JavaScript rendering, real browser interaction, screenshots, or form automation.
Upstream project: https://github.com/vercel-labs/agent-browser
Platform Support
vercel-labs/agent-browser provides native builds for:
- macOS ARM64 / x64
- Linux ARM64 / x64
- Windows x64
Windows support in this skill targets Windows 11 x64 with PowerShell and Node.js 18+.
Prerequisites
-
Node.js 18+
-
npm available in PATH
-
Network access to install agent-browser and download Chromium
-
About 500 MB free disk space for Chromium
-
The node binary on PATH must actually execute code, not just print a version. agent-browser spawns a Node child process internally; if that Node is broken, the daemon will crash with no useful output even when agent-browser --version works.
Quick check:
node -e "console.log('ok')"
If this does not print ok (SIGILL / exit 133 / any crash), the Node on PATH is unusable. Fix it, or run agent-browser with a known-good Node prepended to PATH for that command only:
PATH="/path/to/working-node/bin:$PATH" agent-browser open <url>
Inspect which Node would be picked up with which -a node.
Installation
Inside the CodeBuddy marketplace, scripts/setup.sh auto-runs these steps on first load. The commands below are for manual setup or reinstall.
Windows PowerShell
npm install -g agent-browser
agent-browser install
macOS / Linux
npm install -g agent-browser
agent-browser install
Linux missing dependencies
agent-browser install --with-deps
Required Command Sequence
The current upstream agent-browser CLI does not require a separate launch command. agent-browser open <url> starts or connects to the browser daemon automatically.
Always follow this order:
- Open target URL.
- Wait for page load when needed.
- Inspect page with
snapshot or snapshot -i.
- Interact with the page.
- Close browser when done.
agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser snapshot
agent-browser close
Session Model
agent-browser runs a persistent background daemon. Understand this before planning multi-step tasks:
- The first
agent-browser open starts a daemon; subsequent commands auto-connect to the same daemon.
- Within one session, cookies, localStorage and login state are preserved across commands.
- Multiple
open calls in the same session navigate the existing browser (no need to close between URLs).
agent-browser close ends the daemon. Only call it when the whole task is finished, not between steps of the same task.
Implication: for a task that visits N URLs, do one open ... snapshot ... chain per URL and one close at the very end, not N open/close pairs.
Execution Principles
Apply these when running command sequences, especially in multi-step tasks:
close is mandatory in finally: whether the task succeeds or fails midway, always run agent-browser close at the end to avoid zombie daemons and leaked Chromium processes.wait is optional and degradable: wait --load networkidle can hang on SPAs that never go idle. If a wait stalls, fall back to wait --load load or skip waiting and snapshot directly. Do not block the whole task on wait.- Reuse the daemon: in the same task, do not
close between intermediate steps. Open once, navigate/interact multiple times, close at the end.
- Prefer
snapshot -i for interaction: when you need to click or type, get interactive element IDs first via snapshot -i, then act on them. Do not guess CSS selectors blindly.
- Use agent-browser's own install channel: for Chromium, runtime, or dependency issues, stay inside agent-browser's own tooling —
agent-browser install, or the playwright-core CLI bundled under $(npm root -g)/agent-browser/node_modules/playwright-core. Do not run npx playwright install in parallel; it can fetch a revision that does not match what agent-browser expects and may time out downloading browsers agent-browser never uses.
- Fail fast on environment errors: if the very first
open fails with daemon / Chromium / SIGILL errors, do not retry the same command repeatedly. Verify the Prerequisite Node check, then consult references/troubleshooting.md.
When NOT to Use
agent-browser launches a real Chromium and consumes hundreds of MB plus a few seconds of cold start. Pick the lighter tool whenever possible:
| Need | Recommended tool |
|---|
| Fetch static HTML, plain text, or markdown of a page | WebFetch |
| Call a JSON / REST API | curl, fetch, or HTTP client |
| Read content already present in raw HTML | WebFetch |
| Render JavaScript-driven pages before reading | agent-browser |
| Click, type, login, or any multi-step interaction | agent-browser |
| Take a visual screenshot for review | agent-browser |
| Reproduce a real user flow end-to-end | agent-browser |
Rule of thumb: if curl <url> already contains the target content in plain HTML, do not start agent-browser.
Essential Commands
| Command | Description |
|---|
agent-browser open <url> | Start or connect to the browser daemon and navigate to a URL. |
agent-browser wait --load networkidle | Wait until network activity is idle. Useful after opening dynamic pages. |
agent-browser snapshot | Get page content as text. |
agent-browser snapshot -i | Get page content with element IDs for interaction. |
agent-browser screenshot | Take a screenshot. |
agent-browser click <selector> | Click an element. |
agent-browser type <selector> <text> | Type text into an input. |
agent-browser close | Close browser and free resources. |
Common Workflows
View webpage content
agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser snapshot
agent-browser close
Take screenshot
agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser screenshot
agent-browser close
Fill form and submit
First get interactive element IDs:
agent-browser open https://example.com/login
agent-browser wait --load networkidle
agent-browser snapshot -i
Then interact with stable selectors or element IDs:
agent-browser type "#username" "myuser"
agent-browser type "#password" "mypassword"
agent-browser click "#submit"
agent-browser close
Extract data from a JavaScript-rendered page
agent-browser open https://example.com/data
agent-browser wait --load networkidle
agent-browser snapshot
agent-browser close
Windows Notes
On Windows, prefer PowerShell for installation and verification:
npm install -g agent-browser
agent-browser install
agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser snapshot
agent-browser close
If the command is not found after installation, restart PowerShell or confirm npm global bin is in PATH:
npm config get prefix
Troubleshooting
For environment problems (daemon won't start, Chromium revision mismatch, SIGILL / Exit 133, install timeouts, etc.), see references/troubleshooting.md. It is organized by symptom so you can diagnose against the actual error message instead of following a fixed script.
Quick checks before going there:
agent-browser not found after install: restart shell, confirm npm global bin is in PATH (npm config get prefix).- Linux browser launch missing system libs:
agent-browser install --with-deps.
- Always run
agent-browser close when a task ends, even on failure paths.
