Skip to content

EliasOulkadi/shokunin / .pack/skills/agent-browser

agent-browser

Verified

agent-browser

Fast browser automation CLI for AI agents. Chrome/Chromium via CDP with accessibility-tree snapshots and compact @eN element refs.

Install: npm i -g agent-browser && agent-browser install

Workflow

Step 1: Navigate to a page

agent-browser goto "https://example.com"
agent-browser wait @e3                           # wait for element to appear
agent-browser html                                # get current DOM snapshot

The goto command navigates to a URL and waits for the page to load. Use wait to ensure specific elements are present before interacting. Always snapshot with html after navigation to get fresh @eN refs.

Step 2: Interact with elements

agent-browser click @e5                           # click element by accessibility ref
agent-browser type @e7 "hello world"              # type into input
agent-browser select @e9 "option-value"           # select dropdown option
agent-browser check @e12                          # toggle checkbox/radio
agent-browser hover @e15                          # hover over element
agent-browser press Enter                         # press keyboard key
agent-browser scroll down 500                     # scroll page by pixels
agent-browser drag @e5 @e20                       # drag element to target
agent-browser upload @e8 "C:\path\to\file.pdf"   # file input upload

All interactions use accessibility-tree element references (@eN). These are stable within a single page snapshot but invalidate after navigation or DOM mutations.

Step 3: Extract data or capture evidence

agent-browser screenshot page.png                 # full-page screenshot
agent-browser screenshot --element @e5 el.png     # element screenshot
agent-browser screenshot --full-page false vp.png # viewport-only screenshot
agent-browser text                                 # visible text content
agent-browser html                                 # full HTML source
agent-browser pdf output.pdf                       # generate PDF
agent-browser console                              # browser console logs
agent-browser network                              # network request log
agent-browser eval "document.querySelector('.price').innerText"  # run JS
agent-browser performance                          # Core Web Vitals metrics
agent-browser accessibility                        # accessibility tree dump

Step 4: Fill and submit forms

agent-browser goto "https://example.com/login"
agent-browser type @e3 "user@example.com"          # email field
agent-browser type @e5 "password123"               # password field
agent-browser click @e7                            # submit button
agent-browser wait @e10                            # wait for post-login element
agent-browser screenshot logged-in.png             # verify success

For complex multi-step forms, screenshot after each step for debugging. Use agent-browser html between steps to get updated element refs if the DOM changes.

Step 5: Handle authentication

agent-browser vault set example.com "user:pass"    # store encrypted credentials
agent-browser vault get example.com                # retrieve credentials
agent-browser auth login "https://example.com"     # automated OAuth/login flow
agent-browser session save mysession               # save cookies + localStorage
agent-browser session load mysession               # restore session state
agent-browser session list                          # list saved sessions

Credentials are encrypted at rest. Sessions persist cookies, localStorage, and IndexedDB across runs. Use sessions to skip repeated login flows.

Step 6: Verify and debug

agent-browser console --errors                     # only error-level logs
agent-browser console --since 30s                  # recent console output
agent-browser network --status 4xx,5xx             # failed requests
agent-browser network --host api.example.com       # filter by host
agent-browser cookies                               # inspect cookies
agent-browser eval "document.title"                # run JS in page context
agent-browser performance                          # Core Web Vitals metrics

Common Workflow Patterns

Navigate and interact

agent-browser goto <url>
agent-browser click @e<ref>               # click element by accessibility ref
agent-browser type @e<ref> "text"         # type into element
agent-browser select @e<ref> "option"     # select from dropdown

Extract data

agent-browser screenshot <path>           # full page screenshot
agent-browser html                        # get current page HTML
agent-browser text                        # get visible text content
agent-browser pdf <path>                  # generate PDF

Browser state

agent-browser console                     # get browser console logs
agent-browser network                     # get network requests
agent-browser cookies                     # get/set cookies
agent-browser session save <name>         # save session state
agent-browser session load <name>         # restore session

Authentication

agent-browser vault set <site> <creds>    # store encrypted credentials
agent-browser vault get <site>            # retrieve and auto-fill
agent-browser auth login <url>            # automated login flow

Load specialized workflows

agent-browser skills get core              # base workflow (always load first)
agent-browser skills get core --full       # full command reference
agent-browser skills get electron          # Electron desktop apps (VS Code, Slack, Discord, Figma)
agent-browser skills get slack             # Slack workspace automation
agent-browser skills get dogfood           # Exploratory testing / QA / bug hunts
agent-browser skills get vercel-sandbox    # Inside Vercel Sandbox microVMs
agent-browser skills get agentcore         # AWS Bedrock AgentCore cloud browsers
agent-browser skills list                  # all available workflows

Error Handling

ErrorCauseFix
Element @eN not foundElement removed from DOM or re-renderedRe-run agent-browser html to get fresh refs and retry
Element @eN not interactableElement hidden, covered, or disabledUse agent-browser html to check visibility; scroll into view first
Page load timeoutNetwork slow, infinite spinner, or redirect loopIncrease timeout with --timeout 30000; check agent-browser console for JS errors
Navigation failedInvalid URL, DNS failure, or certificate errorVerify URL format; check network with agent-browser network
Authentication failedExpired session, changed credentials, CAPTCHARe-login manually with agent-browser session save; update vault credentials
Browser not foundChrome/Chromium not installedRun agent-browser install to download compatible Chromium
Port already in useAnother instance of agent-browser runningKill existing process or use --port <alt> to pick a different CDP port
Screenshot black/emptyPage not fully rendered or GPU issueWait for visible element first; try --full-page false for viewport only
Stale element referenceDOM mutated between snapshot and interactionAlways re-snapshot with agent-browser html before interacting
Rate limiting / bot detectionSite detects automationUse agent-browser session load with real browser fingerprint; add delays between actions

Anti-Patterns

PatternProblemFix
Hardcoding @eN refs across pagesRefs change on every navigationAlways snapshot after navigation, never reuse stale refs
Clicking without waitingElement may not be readyUse agent-browser wait @eN before interacting
Blindly typing into any fieldMay type into wrong or readonly fieldVerify element type from snapshot, use proper type/select/check
Ignoring console errorsHidden JS failures break interactionsAlways check agent-browser console --errors after issues
Forgetting to save sessionRe-authentication needed on every runagent-browser session save after manual login
Running without headless mode checkVisual inspection needed for debuggingUse --headless false when debugging; screenshot after each step
Bulk-extracting without rate limitsTriggering bot protection and IP bansAdd --delay 500 between actions; respect robots.txt
Using XPath or CSS selectors directlyFragile, breaks on minor DOM changesPrefer accessibility-tree @eN refs; fall back to text content matching

Troubleshooting Quick Reference

IssueFirst Command to Run
Element not foundagent-browser html
Page not loadingagent-browser console
Auth failingagent-browser session load <name>
Weird layoutagent-browser screenshot debug.png
Network errorsagent-browser network --status 4xx,5xx
Performance issuesagent-browser performance
Blank page after gotoagent-browser console --errors; agent-browser eval "document.readyState"
Click does nothingagent-browser html (check element type, visibility, disabled state)

Why agent-browser

  • Fast native Rust CLI, not a Node.js wrapper
  • Works with any AI agent (Cursor, Claude Code, Codex, Continue, Windsurf, etc.)
  • Chrome/Chromium via CDP with no Playwright or Puppeteer dependency
  • Accessibility-tree snapshots with element refs for reliable interaction
  • Sessions, authentication vault, state persistence, video recording

Checklist

  • Page loaded and rendered without errors before interacting
  • Selectors use stable attributes (data-testid, aria-label) not dynamic classes
  • Screenshots taken at each meaningful step for debugging
  • Timeout set per-action (default 30s) to avoid indefinite hangs
  • Browser context closed in finally block to prevent orphan processes

Sources

  • Accessibility Tree specification (w3.org/TR/accname-1.2)
  • agent-browser CLI (npm: agent-browser)
  • Vercel Sandbox microVMs (vercel.com/docs/sandbox)
  • AWS Bedrock AgentCore (docs.aws.amazon.com/bedrock)
  • Electron CDP support (electronjs.org/docs/latest/api/debugger)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall