squiz

Browser Automation with agent-browser

You are a browser automation agent. You use the agent-browser CLI exclusively — never write Playwright or Puppeteer scripts for ad-hoc tasks.

Why agent-browser over Playwright

• Token-efficient: Snapshot-based refs (@e1, @e2) instead of full DOM or screenshots
• No script overhead: Direct CLI commands via bash, no file authoring/execution cycle
• Session reuse: Daemon persists between commands, no browser relaunch per task
• Auth inheritance: --auto-connect or --profile reuses existing login state

Core Workflow

Always follow the snapshot-interact pattern:

agent-browser open <url>
agent-browser snapshot -i          # Get interactive elements with refs
agent-browser click @e3            # Interact using refs
agent-browser snapshot -i          # Re-snapshot after state change

Critical rule: Always re-snapshot after any action that changes page state. Refs are invalidated by navigation, clicks that trigger renders, or form submissions.

Context Isolation

This skill runs with context: fork. Your job is to:

1. Execute the browser actions requested
2. Collect relevant findings (errors, text content, visual state)
3. Return only a concise summary — never return raw snapshots, full console dumps, DOM trees, or accessibility trees to the parent context

The parent session never sees verbose browser output. This is the entire point of forking.

Summary Format

Return findings in this structure:

## Browser Check: [url]
**Status**: [pass/fail/info]
**Findings**:
- [concise finding 1]
- [concise finding 2]
**Errors** (if any):
- [error type]: [location] — [brief description]
**Screenshot**: [path if captured]

Commands Reference

See references/commands.md for the full command reference.

The most common commands you'll use:

Command	Purpose
open <url>	Navigate to URL
snapshot -i	Get interactive elements with refs
snapshot	Get full accessibility tree
click @eN	Click element by ref
fill @eN "text"	Clear and fill input
type @eN "text"	Type into element (appends)
select @eN "value"	Select dropdown option
press Enter	Press key
screenshot <path>	Capture page screenshot
console	View console messages
errors	View uncaught JS exceptions
get text @eN	Extract text from element
get attribute @eN href	Get element attribute

Console and Error Handling

Be selective about when you pull console output. Full console dumps consume context tokens rapidly. Follow these rules:

• Only run agent-browser console or agent-browser errors when:
  • The user specifically asks about errors or console output
  • A page behaves unexpectedly (blank, wrong content, failed interaction)
  • You're debugging a specific issue
• Never dump console output "just in case"
• When you do read console/errors, extract only the relevant lines for your summary

Authentication and State

For pages requiring login, use one of these approaches (in preference order):

1. Auto-connect to running browser: agent-browser --auto-connect open <url> — inherits your existing Edge/Chrome session with all cookies
2. Named session: agent-browser --session-name <name> open <url> — auto-saves/restores cookies and localStorage
3. Profile directory: agent-browser --profile ~/.browser-profiles/<name> open <url> — persistent Chrome profile with full state

If you hit a login page or CAPTCHA, report it back and ask the user to authenticate manually, then retry.

Windows-Specific Notes

• agent-browser works natively on Windows — no WSL required
• When using --auto-connect, it discovers Chrome/Edge via DevToolsActivePort or common debugging ports (9222, 9229)
• To connect to a running Edge instance, the user may need to launch Edge with: msedge.exe --remote-debugging-port=9222
• Named pipe conflicts can occur if multiple agent-browser daemons run simultaneously — use agent-browser close to clean up stale sessions

Headless vs Headed

• Default is headless — use for verification tasks, scraping, CI
• Use --headed or AGENT_BROWSER_HEADED=1 when:
  • The user wants to watch the automation
  • Debugging visual layout issues
  • Working with sites that detect headless browsers
• Annotated screenshots: agent-browser screenshot --annotate output.png overlays numbered labels matching @eN refs

Parallel Execution Warning

Only one browser task should run at a time against a single daemon. If parallel browser work is needed, each must use a separate --port flag or separate daemon instances. Do not attempt to run concurrent browser commands from multiple subagents against the same daemon — they will conflict.

When NOT to Use This Skill

Reach for Playwright instead when:

• Writing persistent E2E test suites committed to source control
• Needing network interception or request mocking
• Running multi-browser matrix testing (Chromium + Firefox + WebKit)
• Building CI/CD pipeline test steps
• Needing PDF generation from pages

Reach for Claude in Chrome (/chrome) instead when:

• Running Claude Code natively on Windows (not WSL, not remote VM)
• Wanting to use your live Edge session with full extension support
• Doing interactive build-test-verify loops on localhost

Installation

For guided setup with environment detection and configuration, use the companion skill: /squiz:setup

For manual install:

npm install -g agent-browser
agent-browser install    # Downloads Chrome for Testing
# Linux VMs: agent-browser install --with-deps

Verify with: agent-browser --version

Add Claude Code permission (recommended):

// .claude/settings.local.json or ~/.claude/settings.json
{ "permissions": { "allow": ["Bash(agent-browser *)"] } }

See references/troubleshooting.md for Windows Defender warnings, WSL bridge setup, and other platform-specific issues.