"I'll start with the default workflow and assess what stage we're at, then continue from there. If everything is done, I'll come back and ask for your decisions. I can also do A/B/C alternatives — let me know if you want me to lay out capabilities and trade-offs."

1. Probe environment — is the dev server running?

   curl http://localhost:3000

   or

   agent-browser open <url>

   with a short timeout.
2. Capture baseline — screenshot + console-error dump + interactive-element snapshot.
3. Run the user's specific test (or the dev-server-verification checklist below if none specified).
4. Diagnose failures with the Browser + Server correlation table.
5. Iterate — fix issue, re-run, repeat (max 2 retry cycles).

• 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
• Specialized skills for Electron apps, Slack, exploratory testing, cloud providers

1. Page loads —

   agent-browser open

   succeeds without timeout
2. No blank page — snapshot shows meaningful content (not empty body)
3. No error overlay — no Next.js/Vite error overlay detected
4. Console errors — evaluate

   document.querySelectorAll('[data-nextjs-dialog]')

   for error modals
5. Key elements render — snapshot

   -i

   shows expected interactive elements
6. Navigation works — if multiple routes exist, verify at least the home route

1. Screenshot the error state:

   agent-browser screenshot error-state.png

2. Capture the error overlay text or console output
3. Close the browser:

   agent-browser close

4. Fix the issue in code
5. Re-run verification (max 2 retry cycles to avoid infinite loops)

• Playwright toolkit for local web apps — check

  webapp-testing

  if appropriate.
• exploratory testing with full repro evidence — check

  dogfood

  if appropriate.
• agent-browser 0.26.0 Linux workarounds (read before dogfood) — check

  dogfood-quirks

  if appropriate.

• scripts/with_server.py

  - Manages server lifecycle (supports multiple servers)

--help

1. Inspect rendered DOM:
   python

   page.screenshot(path='/tmp/inspect.png', full_page=True)
   content = page.content()
   page.locator('button').all()

2. Identify selectors from inspection results
3. Execute actions using discovered selectors

• Use bundled scripts as black boxes - To accomplish a task, consider whether one of the scripts available in

  scripts/

  can help. These scripts handle common, complex workflows reliably without cluttering the context window. Use

  --help

  to see usage, then invoke directly.
• Use

  sync_playwright()

  for synchronous scripts
• Always close the browser when done
• Use descriptive selectors:

  text=

  ,

  role=

  , CSS selectors, or IDs
• Add appropriate waits:

  page.wait_for_selector()

  or

  page.wait_for_timeout()

• examples/ - Examples showing common patterns:

  • element_discovery.py

    - Discovering buttons, links, and inputs on a page

  • static_html_automation.py

    - Using file:// URLs for local HTML

  • console_logging.py

    - Capturing console logs during automation

• browser automation CLI (general + dev-server verify) — check

  agent-browser

  if appropriate.
• exploratory testing with full repro evidence — check

  dogfood

  if appropriate.
• agent-browser 0.26.0 Linux workarounds (read before dogfood) — check

  dogfood-quirks

  if appropriate.