Agent Browser

agent-browser

agent-browser is the fresh-session deterministic browser verification skill in this repo.

Use it when the real need is: open a clean disposable browser, inspect the current page state, perform one concrete action, and prove what changed with explicit evidence. The key behaviors are isolation, stable refs from snapshots, and an observe → act → observe verification loop.

When to use this skill

Use agent-browser when the task needs one or more of these:

• a clean reproducible browser session instead of the user's real browser profile
• deterministic form checks, navigation checks, and page-state verification
• structured snapshot refs (@e1, @e2, …) before interacting with the page
• explicit before/after evidence such as snapshot diffs, screenshots, or extracted text
• CI-style or automation-friendly browser checks where reproducibility matters more than session continuity
• isolated parallel browser tasks with named sessions

Do not use agent-browser by default for:

• reusing the browser the user already has open, with live cookies, extensions, or trusted-device state → playwriter
• exact rendered-UI review packets or annotation handoff from a human reviewer → agentation
• plan review, diff approval, or artifact sign-off workflows → plannotator
• vague broad web-task autonomy when the real need is a stateful authenticated browser lane

Quick routing rule

Instructions

Step 1: Confirm the browser lane

Choose agent-browser only when a fresh session is the correct default. If the task depends on the user's existing browser state, route out before doing setup work.

Step 2: Follow the core loop

Always use the same loop:

1. Open a clean browser session 2. Wait for a stable page state 3. Observe first with snapshot -i 4. Act once using fresh refs 5. Observe again before the next action 6. Verify with explicit evidence

This is the repo's browser-verification contract. If you skip the observe steps, you lose the deterministic part of the workflow.

Step 3: Start from the smallest useful command set

agent-browser open https://example.com/form
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser click @e2
agent-browser snapshot -i

Rules:

• Never keep using old @eN refs after navigation or meaningful DOM change.
• Prefer wait --load networkidle or a targeted wait over fixed sleeps.
• Keep one browser action between observations when debugging or verifying.

Step 4: Choose one verification mode

Prefer the lightest mode that proves the change. Use screenshots when visual truth matters; do not use them as the only default.

Step 5: Use named sessions for isolation

agent-browser --session signup-check open https://example.com/signup
agent-browser --session settings-check open https://example.com/settings
agent-browser session list

Use one named session per autonomous worker or test lane. Close sessions when finished.

Step 6: Keep authentication bounded

A clean-session skill can still save or load auth state, but that should stay explicit:

agent-browser open https://app.example.com/login
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json

Then later:

agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard
agent-browser snapshot -i

Use this for bounded reproducible reuse. If the real workflow depends on a long-lived personal browser, passkeys, SSO handoff, extensions, or active human browsing, route to playwriter instead.

Step 7: Use complex evaluation payloads safely

For multi-line JavaScript or extraction logic, prefer stdin so shell quoting does not destroy the payload:

agent-browser eval --stdin <<'EVALEOF'
JSON.stringify({
  title: document.title,
  links: document.links.length,
  buttons: document.querySelectorAll('button').length
})
EVALEOF

High-value command patterns

Clean browser check

agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser get url

Form submission with verification

agent-browser open https://example.com/form
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser fill @e1 "hello@example.com"
agent-browser click @e2
agent-browser diff snapshot

Visual regression slice

agent-browser open https://example.com/pricing
agent-browser wait --load networkidle
agent-browser screenshot baseline.png
agent-browser click @e5
agent-browser diff screenshot --baseline baseline.png

Session cleanup

agent-browser --session signup-check close
agent-browser close

Safety and reliability

• Fresh refs only: re-run snapshot -i after navigation or major DOM updates.
• Prefer deterministic waits over fixed sleeps.
• Keep authentication files out of version control.
• Use allowed-domain and action-policy guards in sensitive runs.
• Prefer one small verified step over a giant multi-action leap.
• Route out aggressively when the task is really about running-browser reuse or exact visual review.

Troubleshooting

Examples

Example 1: Repeatable checkout verification

• Prompt: "Run a clean browser check that fills the checkout form and proves the confirmation state appears."
• Expected behavior: choose agent-browser, use a fresh session, observe before/after, and verify with an explicit diff or extracted state.

Example 2: Logged-in personal browser flow

• Prompt: "Use my existing signed-in browser tabs to change a billing setting."
• Expected behavior: route to playwriter, because session continuity is the real requirement.

Example 3: Human leaves exact UI feedback

• Prompt: "I need to click the broken UI and send the exact selector/path to the agent."
• Expected behavior: route to agentation, because rendered-UI annotation is the real deliverable.

Best practices

1. Choose agent-browser because a clean browser matters, not because the word "browser" appears. 2. Follow observe → act → observe every time the page meaningfully changes. 3. Prefer semantic evidence (snapshot diff, extracted state) before visual evidence when it proves the point. 4. Keep auth reuse explicit and bounded; do not slide into a stateful personal-browser workflow by accident. 5. Use named sessions for concurrency and close them when done. 6. Report what was verified, not just what was clicked.

References

Deep-dive docs in this skill:

• modes-and-routing
• commands
• snapshot-refs
• session-management
• authentication

Primary sources:

• https://github.com/vercel-labs/agent-browser
• https://agent-browser.dev
• https://playwright.dev/docs/locators
• https://playwright.dev/docs/aria-snapshots

Ready templates:

• ./templates/form-automation.sh
• ./templates/capture-workflow.sh

Authentication workflows

Boundary first

agent-browser can save and load auth state, but it is still the clean-session browser lane.

Use explicit auth-state files when you need bounded reproducible reuse. If the task depends on the user's already-open browser, passkeys, active SSO state, extensions, or trusted-device continuity, route to playwriter instead.

Login once, save bounded state

agent-browser open https://app.example.com/login
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json

Reuse saved auth state later

agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard
agent-browser snapshot -i

Security notes

• Prefer environment variables or a secret manager for credentials.
• Do not commit auth files to the repository.
• Scope auth-state files per environment and rotate them regularly.
• Treat saved auth as a bounded automation artifact, not a substitute for a real running-browser workflow.

agent-browser commands quick reference

Core navigation and discovery

agent-browser open <url>
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser snapshot -i -C
agent-browser snapshot -s "#main"

Interaction

agent-browser click @e1
agent-browser fill @e2 "text"
agent-browser type @e2 "append text"
agent-browser select @e3 "Option"
agent-browser check @e4
agent-browser press Enter

Verification and capture

agent-browser diff snapshot
agent-browser screenshot before.png
agent-browser diff screenshot --baseline before.png
agent-browser screenshot --annotate
agent-browser pdf output.pdf

Session and utility

agent-browser --session task-a open https://example.com
agent-browser session list
agent-browser get text @e1
agent-browser get url
agent-browser close

Security hardening

export AGENT_BROWSER_CONTENT_BOUNDARIES=1
export AGENT_BROWSER_MAX_OUTPUT=50000
export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"
export AGENT_BROWSER_ACTION_POLICY=./policy.json

Eval safety pattern

Prefer stdin for complex JavaScript:

agent-browser eval --stdin <<'EVALEOF'
JSON.stringify({ title: document.title, links: document.links.length })
EVALEOF

Modes and routing

Core boundary

agent-browser owns fresh-session deterministic verification.

Use it when the job needs:

• a clean disposable browser
• stable snapshot refs for actions
• explicit before/after evidence
• CI-style or automation-friendly reproducibility

Do not use it as the default lane for:

• the user's already-open browser or trusted-device state → playwriter
• exact rendered-UI annotation packets → agentation
• plan or diff approval → plannotator

Verification modes

Routing checklist

Ask these in order: 1. Does the workflow need a clean browser? If yes, continue with agent-browser. 2. Does it need the user's real browser state, extensions, or live tabs? If yes, route to playwriter. 3. Is the output a human UI annotation packet? If yes, route to agentation. 4. Is the artifact a plan or diff under review? If yes, route to plannotator.

Practical rule

A browser skill gets more reusable when it answers one question clearly:

"Can I prove this website state in a clean disposable session?"

If the answer is yes, use agent-browser. If the task is really about stateful reuse or human visual feedback, route out early.

Session management patterns

Isolate concurrent tasks

Use named sessions to prevent cookie/storage collisions.

agent-browser --session research open https://example.com
agent-browser --session checkout open https://shop.example.com

Verify active sessions

agent-browser session list

Cleanup discipline

Always close sessions at end of task:

agent-browser --session research close
agent-browser --session checkout close

State persistence

Use explicit save/load when a flow requires auth reuse:

agent-browser state save auth.json
agent-browser state load auth.json

Operational guardrails

• Assign one session per autonomous worker.
• Do not share a session between unrelated workflows.
• Close sessions even on failure paths.

Snapshot refs lifecycle

Deterministic loop

1. open 2. snapshot -i 3. interact with @eN 4. re-run snapshot -i after updates

Why refs fail

Refs become stale after:

• navigation
• form submit with rerender
• modal open/close that rebuilds DOM
• SPA route transitions

Safe usage pattern

agent-browser snapshot -i
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i

Snapshot minimization

Use smaller snapshots to control context size:

agent-browser snapshot -i -c
agent-browser snapshot -i -d 4
agent-browser snapshot -s "#content"

Common recovery

• If click targets wrong element: snapshot again and verify label text.
• If element not found: wait by selector/ref, then snapshot.
• If tree is noisy: scope with -s and use compact mode.