A fast Rust-based headless browser automation CLI with Node.js fallback that enables AI agents to navigate, click, type, and snapshot pages via structured commands.
Agent BrowserInstallationnpm recommendedFrom SourceQuick StartUsing Real Chrome Profile (for OAuth/Logged-in Sessions)Terminal 1: Launch Chrome with your real profile and remote debuggingTerminal 2: Connect agent-browser to that Chrome instanceThis reuses your existing Google session - no re-login needed!Works for: Google OAuth, Discord OAuth, any site you're logged into in ChromeFirst time: headed mode, login manuallyComplete Google OAuth manually in the browser window
A fast Rust-based headless browser automation CLI with Node.js fallback that enables AI agents to navigate, click, type, and snapshot pages via structured commands.
---
name: Agent Browser
description: A fast Rust-based headless browser automation CLI with Node.js fallback that enables AI agents to navigate, click, type, and snapshot pages via structured commands.
read_when:
- Automating web interactions
- Extracting structured data from pages
- Filling forms programmatically
- Testing web UIs
metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["node","npm"]}}}
---
# Agent Browser
A fast Rust-based headless browser automation CLI with Node.js fallback that enables AI agents to navigate, click, type, and snapshot pages via structured commands.
## Installation
### npm recommended
```bash
npm install -g agent-browser
agent-browser install
agent-browser install --with-deps
```
### From Source
```bash
git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
agent-browser install
```
## Quick Start
```bash
agent-browser open example.com
agent-browser snapshot
agent-browser click @e2
agent-browser fill @e3 "[email protected]"
agent-browser get text @e1
agent-browser screenshot page.png
agent-browser close
```
## Using Real Chrome Profile (for OAuth/Logged-in Sessions)
For sites requiring Google/Discord/etc login (like star-swap.com):
**Method 1: Launch Chrome with custom profile, connect via CDP**
```bash
# Terminal 1: Launch Chrome with your real profile and remote debugging
google-chrome --remote-debugging-port=9222 --user-data-dir=/home/willr/.config/google-chrome/Default &
# Terminal 2: Connect agent-browser to that Chrome instance
agent-browser --cdp 9222 open "https://star-swap.com"
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 click e2
# This reuses your existing Google session - no re-login needed!
# Works for: Google OAuth, Discord OAuth, any site you're logged into in Chrome
```
**Method 2: Session persistence (first-time manual login)**
```bash
# First time: headed mode, login manually
agent-browser --headed --session starswap open "https://star-swap.com"
# Complete Google OAuth manually in the browser window
# Close when done
# Future runs: cookies persist!
agent-browser --session starswap open "https://star-swap.com"
# Already logged in automatically
```
**am.will.ryan Chrome profile:** `/home/willr/.config/google-chrome/Default`
## Core Commands
### Navigation
```bash
agent-browser open
agent-browser back
agent-browser forward
agent-browser reload
```
### Interaction
```bash
agent-browser click
agent-browser dblclick
agent-browser focus
agent-browser type
agent-browser fill
agent-browser clear
agent-browser press
agent-browser keydown
agent-browser keyup
agent-browser hover
agent-browser select
agent-browser check
agent-browser uncheck
agent-browser drag
agent-browser upload
```
### Extraction and Info
```bash
agent-browser snapshot
agent-browser get text
agent-browser get html
agent-browser get value
agent-browser get attr
agent-browser get title
agent-browser get url
agent-browser get count
agent-browser get box
agent-browser screenshot [path]
agent-browser pdf
```
### Check State
```bash
agent-browser is visible
agent-browser is enabled
agent-browser is checked
```
### Find Elements
- agent-browser find role [value]
- agent-browser find text
- agent-browser find label [value]
- agent-browser find placeholder [value]
- agent-browser find alt
- agent-browser find title
- agent-browser find testid [value]
Actions include click, fill, check, hover, and text.
### Wait and Timing
```bash
agent-browser wait
agent-browser wait
agent-browser wait --text "Welcome"
agent-browser wait --url "**/dash"
agent-browser wait --load networkidle
```
### Advanced Control
```bash
agent-browser scroll [px]
agent-browser scrollintoview
agent-browser eval
agent-browser mouse move
agent-browser cookies
agent-browser storage local
agent-browser tab new [url]
agent-browser frame
agent-browser dialog accept [text]
```
## Sessions
Run multiple isolated browser instances.
```bash
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com
```
## Snapshot Options
The snapshot command supports filtering to reduce output size.
- agent-browser snapshot -i
- agent-browser snapshot -c
- agent-browser snapshot -d 3
- agent-browser snapshot -s "#main"
## Selectors and Refs
Refs provide deterministic element selection from snapshots. Use the @ref syntax.
```bash
agent-browser snapshot
agent-browser click @e2
```
## Agent Mode
Use --json for machine readable output.
```bash
agent-browser snapshot --json
```
### Optimal AI Workflow
- Navigate with agent-browser open
- Observe with agent-browser snapshot -i --json
- Act with @ref from the snapshot
- Verify with agent-browser snapshot
## Troubleshooting
- If the command is not found on Linux ARM64, use the full path in the bin folder.
- If an element is not found, use snapshot to find the correct ref.
- If the page is not loaded, add a wait command after navigation.
- Use --headed to see the browser window for debugging.
## Options
- --session uses an isolated session.
- --json provides JSON output.
- --full takes a full page screenshot.
- --headed shows the browser window.
- --timeout sets the command timeout in milliseconds.
## Notes
- Refs are stable per page load but change on navigation.
- Always snapshot after navigation to get new refs.
- Use fill instead of type for input fields to ensure existing text is cleared.