agent-browser

name	agent-browser
description	Fast browser automation CLI optimized for AI agents with semantic element references and accessibility tree. Use when needing AI-friendly web scraping, element interaction with minimal context, or structured data extraction. Triggers on "agent browser", "semantic web scraping", "AI browser automation", "accessibility tree", "web data extraction".
user-invocable	false
allowed-tools	Read, Write, Bash, Glob
version	1.0.0
scope	public

Agent Browser

Fast browser automation CLI designed for AI agents with semantic element references and accessibility tree snapshots.

---

Integrations

provides-to:
  - skill: *
    capability: AI-optimized web scraping with element references

replaces:
  - skill: browser-automation (archived)
    reason: AI-friendly accessibility tree, lower token usage, better session isolation

---

Architecture

+-----------------------------------------------------------+
|                   Agent Browser CLI                        |
+-------------+-------------+-------------+-----------------+
|  Navigation | Interaction |  Snapshot   |   Sessions      |
|  open/back  | click/type  | refs(@e1)   |   isolated      |
+-------------+-------------+-------------+-----------------+
                           |
                           v
                   +--------------+
                   |   Daemon     |
                   | (Playwright) |
                   +--------------+

Core advantages:

• Element references (@e1, @e2) instead of CSS selectors
• Accessibility tree instead of full DOM
• JSON output mode for easy parsing
• Daemon architecture for better performance
• Session isolation

---

X/Twitter Thread Reading (Important)

X/Twitter requires login to view thread replies. Do not say "unable to view"; use the following method:

Quick command

python3 ~/.claude/skills/agent-browser/scripts/read-x-thread.py <tweet_url>

Session location

~/.claude/skills/notebooklm/data/browser_state/x_profile

Re-login if needed

python3 ~/.claude/skills/agent-browser/scripts/read-x-thread.py <tweet_url> --login

See the "X/Twitter Thread Reading" section in ./references/anti-scraping.md for details.

---

Installation

# Already installed (global)
pnpm add -g agent-browser

# Download Chromium (already done)
agent-browser install

---

Quick Start

# 1. Open a webpage
agent-browser open example.com

# 2. Get interactive elements
agent-browser snapshot --interactive --compact --json

# 3. Click an element (using ref)
agent-browser click @e1

# 4. Fill a form
agent-browser fill @e2 "text input"

# 5. Take a screenshot
agent-browser screenshot --full output.png

---

Core Commands

Navigation

agent-browser open <url>           # Navigate to URL
agent-browser back                 # Go back
agent-browser forward              # Go forward
agent-browser reload               # Reload

Snapshot (Core Feature)

# Basic usage
agent-browser snapshot

# AI-optimized mode
agent-browser snapshot --interactive --compact --json

# Limit depth
agent-browser snapshot --depth 3

# Limit scope
agent-browser snapshot --selector "main"

Output format:

{
  "success": true,
  "data": {
    "refs": {
      "e1": {"name": "Submit", "role": "button"},
      "e2": {"name": "Email", "role": "textbox"}
    },
    "snapshot": "- button \"Submit\" [ref=e1]\n- textbox \"Email\" [ref=e2]"
  }
}

Ref lifecycle rule: @e1, @e2 etc. are valid only for the current page state. They expire after any navigation (open, back, forward, reload) or when the page updates its DOM. Always re-snapshot at the start of each page or loop iteration before using refs.

Interaction

# Using element references
agent-browser click @e1
agent-browser type @e2 "hello"
agent-browser fill @e3 "replace text"
agent-browser check @e4            # checkbox
agent-browser select @e5 "option"  # dropdown

# Using selectors
agent-browser click "button.submit"
agent-browser type "input[name=email]" "[e-mail]"

Get Information

agent-browser get text @e1
agent-browser get html @e1
agent-browser get value @e1
agent-browser get attr href @e1
agent-browser get title
agent-browser get url

Find Elements

# Semantic locators
agent-browser find role button click --name Submit
agent-browser find text "Login" click
agent-browser find label "Email" fill "[e-mail]"
agent-browser find placeholder "Search..." type "query"

Screenshots & PDF

agent-browser screenshot              # Current viewport
agent-browser screenshot --full       # Full page
agent-browser screenshot output.png   # Specified path
agent-browser pdf output.pdf          # Save as PDF

Sessions

# Isolated session (isolated cookies/storage)
agent-browser --session mywork open example.com

# List sessions
agent-browser session list

# Environment variable
export AGENT_BROWSER_SESSION=mywork
agent-browser open example.com

---

Anti-Scraping Techniques

IMPORTANT: When encountering anti-scraping protection, read ./references/anti-scraping.md for advanced techniques learned from notebooklm skill:

• Persistent browser context (maintained session state)
• Stealth mode (remove automation fingerprints)
• Cookie injection (manual auth -> automated access)
• Human-like behavior (random delays, realistic typing)
• Realistic headers & user-agent

Quick Anti-Scraping Setup:

# Persistent session with stealth
export AGENT_BROWSER_SESSION=stealth
export AGENT_BROWSER_USER_DATA_DIR=~/.agent-browser/profiles/stealth
export AGENT_BROWSER_ARGS="--disable-blink-features=AutomationControlled --no-first-run"

agent-browser \
  --user-agent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  open https://example.com

See ./references/anti-scraping.md for complete patterns and real-world examples.

---

Common Patterns

Pattern 1: Semantic Data Scraping

#!/bin/bash

# 1. Navigate
agent-browser open https://news.ycombinator.com

# 2. Get structured elements
SNAPSHOT=$(agent-browser snapshot -i -c --json)

# 3. Parse and interact
# refs contain all interactive elements, process with jq
echo "$SNAPSHOT" | jq '.data.refs'

# 4. Click the first link
agent-browser click @e1

Pattern 2: Form Filling and Submission

# 1. Open login page
agent-browser open https://example.com/login

# 2. Find form elements
agent-browser snapshot -i --json | jq '.data.refs'

# 3. Fill form (assuming e1=email, e2=password, e3=submit)
agent-browser fill @e1 "[e-mail]"
agent-browser fill @e2 "password"
agent-browser click @e3

# 4. Wait for navigation
agent-browser wait 2000

Pattern 3: Multi-Step Data Collection

#!/bin/bash

SESSION="scraper-$(date +%s)"

# Use isolated session
agent-browser --session "$SESSION" open https://example.com

# Login
agent-browser --session "$SESSION" fill @e1 "[e-mail]"
agent-browser --session "$SESSION" click @e2

# Navigate to target page
agent-browser --session "$SESSION" open https://example.com/data

# Scrape data
agent-browser --session "$SESSION" snapshot --json > data.json

# Multi-page scraping
for page in {1..5}; do
  agent-browser --session "$SESSION" open "https://example.com/page/$page"
  agent-browser --session "$SESSION" snapshot --json >> "page-$page.json"
done

Pattern 4: Web Monitoring

#!/bin/bash

# Monitor webpage changes
while true; do
  agent-browser open https://example.com/status

  # Re-snapshot every iteration: refs expire after each open/reload
  STATUS=$(agent-browser snapshot -i --json)

  # Check for specific element
  if echo "$STATUS" | jq -e '.data.refs | has("e1")' > /dev/null; then
    echo "Element found!"
    break
  fi

  sleep 60
done

Pattern 5: Anti-Scraping Bypass (Advanced)

#!/bin/bash
# anti-scraping-pattern.sh - Persistent session with stealth

SESSION_NAME="stealth-scraper"
PROFILE_DIR="$HOME/.agent-browser/profiles/$SESSION_NAME"

# Setup persistent session
export AGENT_BROWSER_SESSION="$SESSION_NAME"
export AGENT_BROWSER_USER_DATA_DIR="$PROFILE_DIR"
export AGENT_BROWSER_ARGS="--disable-blink-features=AutomationControlled --no-first-run"

# Random delay helper
random_delay() {
    local min=${1:-200}
    local max=${2:-800}
    local delay=$((RANDOM % (max - min + 1) + min))
    agent-browser wait $delay
}

echo "Starting stealth scraper..."

# 1. Setup realistic browser
agent-browser set viewport 1920 1080

# 2. Navigate with stealth
agent-browser \
    --user-agent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" \
    --headers '{"Accept-Language": "en-US,en;q=0.9", "DNT": "1"}' \
    open https://example.com

random_delay 1000 2000  # Human think time

# 3. Human-like interaction
SNAPSHOT=$(agent-browser snapshot -i --json)
random_delay 500 1500

agent-browser click @e1
random_delay 800 2000

agent-browser fill @e2 "search query"
random_delay 300 700

agent-browser click @e3  # Submit

# 4. Extract data
agent-browser wait 2000
agent-browser snapshot --json > results.json

echo "Scraping complete"

Key Anti-Scraping Techniques Used:

• Persistent session (AGENT_BROWSER_USER_DATA_DIR)
• Stealth flags (--disable-blink-features=AutomationControlled)
• Realistic user-agent and headers
• Random delays (200-2000ms) mimicking human behavior
• Common viewport size (1920x1080)

For advanced cases (cookie injection, manual auth), see ./references/anti-scraping.md.

---

Why Agent-Browser (Replaces browser-automation)

Feature	browser-automation (deprecated)	agent-browser
Architecture	Node.js scripts + puppeteer-core	Rust CLI + Playwright daemon
Element targeting	CSS selectors	Semantic refs (@e1) + ARIA
Output	Raw DOM/JavaScript	Accessibility tree
AI friendliness	Requires DOM parsing	Provides structured refs directly
Context usage	High (full DOM)	Low (filtered tree)
Profile management	Manual copy	Built-in session isolation
Interactive selector	pick.js	Built-in find commands
Performance	Manual connection management	Daemon persistence

Agent-browser is the only choice:

• AI-driven automation, semantic elements, session isolation
• Need complex JavaScript? Use the eval command or consider alternatives

---

Advanced Usage

JSON Output Mode

All commands support --json output:

agent-browser --json open example.com
# {"success": true, "data": {"title": "Example Domain"}, "error": null}

agent-browser --json get text @e1
# {"success": true, "data": "Button Text", "error": null}

Headed Mode (Visual Debugging)

agent-browser --headed open example.com
# Shows browser window

Custom Browser

# Use local Chrome
export AGENT_BROWSER_EXECUTABLE_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
agent-browser open example.com

# Or use parameter
agent-browser --executable-path "/path/to/chrome" open example.com

Load Extensions

agent-browser --extension /path/to/extension open example.com

Set Headers (Authentication)

agent-browser --headers '{"Authorization": "Bearer token"}' open https://api.example.com

Network Control

# Intercept requests
agent-browser network route "https://example.com/api/*" --abort

# Mock responses
agent-browser network route "https://example.com/api/data" --body '{"mock": "data"}'

# View requests
agent-browser network requests --json

Device Emulation

agent-browser set device "iPhone 13"
agent-browser set viewport 375 812
agent-browser set media dark reduced-motion

---

Troubleshooting

Daemon Not Starting

# agent-browser auto-starts the daemon
# If there are issues, check daemon status
ps aux | grep agent-browser

# Force restart (closes all sessions)
pkill -f agent-browser

Session Conflicts

# Use isolated session
agent-browser --session unique-name open example.com

# Or clear default session
rm -rf ~/.agent-browser/sessions/default

Element Reference Expired

# @e1, @e2 etc. refs become invalid after page reload
# Solution: re-snapshot before each operation

agent-browser open example.com
REFS=$(agent-browser snapshot -i --json)
agent-browser click @e1  # Valid

agent-browser reload
agent-browser click @e1  # Ref expired

# Re-snapshot
REFS=$(agent-browser snapshot -i --json)
agent-browser click @e1  # Valid again

Element Not Found

# Use wait to wait for element to load
agent-browser wait "button.submit"
agent-browser wait 2000  # Or wait for time (ms)

# Use a broader snapshot
agent-browser snapshot --json  # Without -i -c, see full tree

---

Security Notes

SSRF Protection (Server-Side Request Forgery)

CRITICAL: agent-browser can access any URL, including internal network resources. URLs must be validated to prevent SSRF attacks.

Forbidden URLs:

• localhost, 127.0.0.1, [::1]
• Internal IP ranges:
  • 10.0.0.0/8 (10.0.0.0 - 10.255.255.255)
  • 172.16.0.0/12 (172.16.0.0 - 172.31.255.255)
  • 192.168.0.0/16 (192.168.0.0 - 192.168.255.255)
  • 169.254.0.0/16 (link-local)
• file:// protocol
• Other loopback addresses

URL validation script (validate before use):

#!/bin/bash
# validate-url.sh
URL="$1"

# Blocklist check
if echo "$URL" | grep -qiE '(localhost|127\.0\.0\.1|\[::1\]|file://|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.)'; then
    echo "SSRF Risk: URL blocked (localhost/internal network)" >&2
    exit 1
fi

echo "URL validated: $URL"
agent-browser open "$URL"

Usage:

# Dangerous: directly using unvalidated URL
agent-browser open "$USER_INPUT_URL"

# Safe: validate URL first
./validate-url.sh "$USER_INPUT_URL"

Other Security Considerations

• Session isolation - Use --session to isolate different tasks
• Header leakage - --headers only applies to that origin
• No profile copying - Unlike CDP, does not copy local Chrome profile
• Element refs are ephemeral - @e1 etc. refs become invalid after page changes

---

Out of Scope

• Complex JavaScript execution - eval is available but less flexible than CDP
• Local Chrome Profile - Cannot directly use local login state (use session + cookies)
• Deep DOM manipulation - Focuses on semantic elements, does not support complex DOM queries
• CAPTCHA bypass - Does not handle automated CAPTCHA solving (supports manual completion only)
• Cloudflare Challenge - Extreme anti-scraping requires manual intervention or external services

Note on Anti-Scraping: Basic to moderate anti-scraping protection CAN be bypassed using techniques in ./references/anti-scraping.md. Only extreme cases (CAPTCHA, Cloudflare) are out of scope for full automation.

---

Verification

Installation Verification

# Check agent-browser is available
agent-browser --help

# Check Chromium is installed
ls ~/Library/Caches/ms-playwright/chromium_headless_shell-*

Functional Verification

# Basic navigation
agent-browser open example.com
# Expected: successfully opens and displays title

# Snapshot JSON
agent-browser snapshot --json
# Expected: returns valid JSON with refs

# Element interaction
agent-browser snapshot -i --json
agent-browser click @e1
# Expected: successfully clicks element

Completion Criteria

• agent-browser CLI installed and available
• Chromium downloaded
• Can successfully navigate and get snapshot
• JSON output mode working
• Element references working

---

Safety and Escalation

Situation	Action
User-provided URL	CRITICAL: Must validate URL first to prevent SSRF attacks
Authentication needed	Use --headers or cookies, don't hardcode passwords
Element ref expired	Re-run snapshot
Need to wait for dynamic content	Use wait <selector> or wait <ms>
Need deep DOM manipulation	Use eval command to execute JavaScript
High-volume requests	Use isolated session and consider rate limiting
Complex site structure	Use snapshot without -i -c to see full tree

Security Principles

1. URL Validation (CRITICAL) - Any user-provided URL must be validated first; reject localhost/internal IPs
2. Session isolation - Use different sessions for different tasks
3. Ref validation - Confirm ref is still valid before interacting
4. Error handling - Check JSON success and error fields
5. Least privilege - Only get necessary elements (use -i -c)

URL validation example:

# Validate URL before calling agent-browser
validate_url() {
    local url="$1"

    # Blocklist check
    if echo "$url" | grep -qiE '(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.|file://)'; then
        echo "Blocked: SSRF risk detected" >&2
        return 1
    fi

    return 0
}

# Usage
if validate_url "$USER_URL"; then
    agent-browser open "$USER_URL"
else
    echo "Invalid URL provided"
fi

---

Handoff

After completion, the agent-browser skill provides:

• AI-optimized browser automation with semantic element references
• Lower context usage than traditional DOM scraping
• Session isolation for concurrent tasks
• JSON output mode for easy parsing

Next steps: integrate into skills that need web scraping (e.g., telegram-learner, data synchronization tasks).