agent-browser

Agent-Browser Driver

The orchestrator routed you here. Use these mechanics to execute your plan.

Control web pages and Electron desktop apps via the agent-browser CLI. Uses Playwright under the hood with a headless Chromium instance managed by a background daemon.

When to use

• Automating web app flows (login, form fill, data extraction, visual QA)
• Driving Electron apps (VS Code, Slack, Discord, Figma, Notion, Spotify)
• Visual verification -- screenshots and annotated element overlays
• DOM-level assertions where terminal snapshots are irrelevant

If the target is a terminal TUI, use tuistory or true-input instead.

Prerequisites

agent-browser install   # one-time: downloads bundled Chromium

For Electron apps, the target app must be launched with --remote-debugging-port=<port>.

Core workflow

Every interaction follows the same loop:

agent-browser open <url>
agent-browser snapshot -i          # interactive elements only -> refs like @e1, @e2
agent-browser click @e3            # interact using refs
agent-browser snapshot

Command chaining

Commands share a persistent daemon, so && chaining is safe:

Chain when you don't need intermediate output. Run separately when you need to parse refs before acting.

Command reference

Navigation

Snapshot (page analysis)

Interactions (use @refs from snapshot)

Semantic locators (when refs are unreliable)

Get information

Check state

Wait

JavaScript (eval)

Diff (compare page states)

Dialogs

Tabs & frames

Screenshots & recording

--annotate overlays numbered labels on interactive elements. Each label [N] maps to ref @eN, enabling both visual verification and immediate interaction.

Video recording:

Recording creates a fresh context but preserves cookies/storage. Explore first, then start recording for smooth demos.

Ref lifecycle

Refs (@e1, @e2, ...) are invalidated whenever the page changes. Always re-snapshot after:

• Clicking links/buttons that navigate
• Form submissions
• Dynamic content loading (dropdowns, modals)

Electron app automation

Any Electron app supports --remote-debugging-port since it's built on Chromium.

Launch and connect

The app must be quit first if already running -- the flag only takes effect at launch.

Tab management in Electron

Electron apps often have multiple windows/webviews:

Electron troubleshooting

State persistence

Save and restore cookies/localStorage across sessions:

Auto-save/restore with named sessions:

Sessions

The browser persists via a background daemon. One session is the default.

Each --session spawns a separate Chromium process (~300 MB). Prefer navigating within a single session. Exception: controlling multiple Electron apps on different CDP ports.

Global options

Debugging

Gotchas

• Invisible-to-snapshot elements. contenteditable divs and custom components may not appear in accessibility snapshots. Use eval to interact:

  agent-browser eval --stdin <<'EVALEOF'
  const el = document.querySelector("[contenteditable]");
  el.focus();
  el.textContent = "hello";
  el.dispatchEvent(new Event('input', { bubbles: true }));
  EVALEOF
• Unstable class names. Never hardcode CSS-in-JS class names (sc-*, css-*). Find elements by text content, cursor: pointer style, or testid instead.
• SPA loading delays. Single-page apps may take 5-10s to render after navigation. Double-wait: wait --load networkidle then wait 5000.
• Flag ordering. Global flags (--headers, --session, --cdp) must come before the subcommand: agent-browser --headers '{}' open <url>.

Critical rules

1. Always take screenshots for visual QA. Text snapshots miss layout, styling, alignment, and z-index issues. Use screenshot --annotate when you need both visual proof and element refs.
2. One session by default. Navigate between pages with open <url> instead of creating new sessions.
3. Always close when done. agent-browser close frees the Chromium process.
4. Re-snapshot after every navigation. Refs are invalidated.**