Agent Browser

Browser Automation with agent-browser

Default Use Policy

Use Agent Browser first when the request involves a rendered webpage, visual proof, screenshots, clicking, filling, login, account setup, OAuth/admin consoles, local web app previews, or any flow where cookies, JavaScript rendering, or browser identity matter.

Use terminal/curl first only for pure API/status/header/DNS checks where rendered browser state is irrelevant. If the task has 3+ independent URLs/pages/sections, switch to browser-swarm; for 1-2 pages, use named Agent Browser sessions directly.

Tab and Session Cleanup Rule

Treat every Agent Browser tab and session as a temporary work surface. Close each tab or session as soon as it is no longer actively needed, especially when a page failed, loaded the wrong account, opened an irrelevant result, or did not produce useful evidence. Do not leave exploratory, failed, duplicate, or finished tabs open for later cleanup.

Before you report that browser work is done, run the smallest appropriate cleanup command for every Agent Browser surface you opened:

agent-browser tab close        # Close one finished tab in the current session
agent-browser close                   # Close the default session/tab
agent-browser --session  close  # Close a named session/tab

Only keep a tab open when it is still needed for an active user-visible state, in-progress login/2FA, or a specific follow-up the user asked to inspect. If you intentionally leave anything open, say exactly which tab/session remains and why. Closing Agent Browser work tabs keeps Chrome usable, reduces memory, and prevents future automations from attaching to stale or dirty pages.

Real Chrome Profile First

For account/login work, payment dashboards, registrar/admin consoles, or any task where the user expects existing cookies, saved passwords, extensions, or their visible desktop Chrome session, use the controller-owned real Chrome CDP profile first. Do not use AGENT_BROWSER_CONFIG=/tmp/agent-browser-clean.json, --profile, --state, or --executable-path for these tasks unless the user explicitly asks for a disposable browser.

Required startup path for real-browser work:

start-chrome-debug 9222
agent-browser --session  connect 9222
agent-browser --session  open 
agent-browser --session  snapshot -i

For parallel real-Chrome work, every named session must connect to CDP before opening pages.

If Agent Browser reports Failed to connect via CDP or localhost:9222 readiness problems, run start-chrome-debug 9222 again and verify with browser-runtime doctor. Only after the real Chrome CDP path is confirmed unavailable should you use a clean temporary config, and when you do, clearly tell the user that it will not have their existing logged-in sessions.

Clean-profile exception: do not start with AGENT_BROWSER_CONFIG=/tmp/agent-browser-clean.json for account work, but switch to it after one real-CDP retry if page loads repeatedly abort, land on extension/offscreen pages, show the wrong browser identity, or fail before login UI appears. State clearly that the clean config will not have the user's cookies, extensions, saved passwords, or logged-in sessions.

Core Workflow

If the task spans 3+ URLs, pages, or independently reviewable sections, do NOT stay in this skill alone. Switch to browser-swarm so setup and review happen in parallel instead of sequentially.

Every browser automation follows this pattern:

1. Navigate: agent-browser open
2. Snapshot: agent-browser snapshot -i (get element refs like @e1, @e2)
3. Interact: Use refs to click, fill, select
4. Re-snapshot: After navigation or DOM changes, get fresh refs
5. Clean up: close finished, failed, duplicate, or no-longer-useful tabs/sessions immediately

agent-browser open https://example.com/form
agent-browser snapshot -i
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i  # Check result

Visual Verification Fast Path

When the user asks to visually inspect, open, show, screenshot, verify what renders, check a page in the browser, or "let me see it", the first browser action must be Agent Browser against the live target page. Do not start with curl probes, DOM classifiers, canvas classifiers, route inventories, package/version checks, or repeated JavaScript probes.

Use this order:

1. Open the target in the real Agent Browser session:

``bash agent-browser --session open ``

1. Wait briefly for first render:

``bash agent-browser --session wait 2000 ``

1. Capture visible evidence immediately:

``bash agent-browser --session screenshot /tmp/.png ``

1. Read/inspect the screenshot and describe what is visible.
2. Only after the screenshot/open path fails, or the screenshot shows a blank/error/frozen page, run focused diagnostics such as agent-browser errors, agent-browser get url, a route HTTP status check, or a small DOM/canvas probe.

WHY: The old visual behavior the user expects is "open it in my real browser and show me what it looks like." Diagnostics are useful after evidence fails, but running them first wastes tokens and can hide the actual visual state behind probe noise. The canonical browser runtime still owns CDP readiness, session identity, and URL translation; this fast path only fixes the action order.

WSL ChromeCDP recovery rule: if Agent Browser reports ChromeCDP/bridge/localhost readiness problems, use the controller-owned runtime path (start-chrome-debug, browser-runtime doctor, and the resolved Windows-reachable URL). Do not enable WSL networkingMode=mirrored; it was removed on this machine after repeated Wsl/Service/CreateInstance/E_FAIL startup failures. For WSL app previews, wait for the dev server to finish compiling, try Windows localhost: first, then use the runtime-resolved WSL IP URL or a narrow app-port portproxy if needed.

Diagnostic budget: once a screenshot shows the expected page, stop probing. If the browser evidence fails, run only the smallest focused set: agent-browser get url, agent-browser errors, one HTTP/status or browser-runtime preflight check, and one targeted DOM/canvas probe. Do not repeat diagnostics unless a recovery step changed the state.

Website Automation Protocol (MANDATORY only for complex sites)

Use this protocol for multi-step, high-risk, unfamiliar, or repeatedly failing flows. For simple screenshots, obvious clicks, page checks, or straightforward forms, use the Core Workflow fast path: open, snapshot, interact, re-snapshot.

Cheap-First Rule

Do NOT default to external WebSearch before using the browser. Start with the live page first.

Default order:

1. Open the page.
2. Snapshot the real UI.
3. Attempt the direct interaction path.
4. Escalate to external research only if the flow is complex, changed, blocked, or high-risk.

Good reasons to search first:

• OAuth/login/consent/admin flows
• complex SPAs with unclear navigation
• high-stakes forms where misclicking is risky
• repeated blockers after observing the live UI

Simple screenshots, page checks, obvious buttons, and straightforward forms should usually skip external research.

Step 1: Research the Website's GUI

Before touching a single element, understand the site:

1. Check for a cached playbook first: Look in references/.md (e.g., references/linkedin.md). If one exists, skip to Step 3 — the research is already done.
2. Use the live page first: snapshot key pages to understand navigation structure:

``bash agent-browser open && agent-browser snapshot -i ``

1. If live inspection is still unclear, then use WebSearch for current UI guidance.
2. Identify all form field types — snapshot the form and classify each field:

• [textbox] / [input] → use fill
• [combobox] → use select or type partial + wait for dropdown + click option
• [contenteditable] → use eval with innerHTML + InputEvent
• [checkbox] → use check/uncheck
• [select] (native HTML) → use select

1. Identify navigation patterns — How do you add new entries? Is there an "Add" button, a dropdown menu, a sidebar link? Where do modals appear?
2. Identify potential blockers — banners, cookie consent, terms updates, overlays that intercept clicks
3. Identify the SPA framework — React, Angular, Vue? This determines whether fill triggers state updates or if you need eval with event dispatch

Step 2: Plan the Execution

1. Map every field to its exact command before starting:

`` Title field: [textbox] → fill @eN "value" Company field: [combobox] → fill @eN "partial" → wait → click option Description: [contenteditable] → eval with innerHTML ``

1. Identify independent tasks that can run in parallel:

• Different profile sections (Experience vs Skills vs Featured)
• Different pages that don't share state
• Different accounts or data sources

1. Assign parallel agents with isolated sessions:

``bash # Each agent gets its own session for tab isolation agent-browser --session task-a open # Agent 1 agent-browser --session task-b open # Agent 2 agent-browser --session task-c open # Agent 3 `` Each worker closes its own session as soon as its assigned browser work is complete or abandoned.

1. Identify sequential dependencies — tasks that MUST happen in order:

• Within a single form: fill fields → save → dismiss post-save dialog → next entry
• Cross-section: if section B depends on section A being saved first

Step 3: Execute

• Follow the field-to-command mapping from Step 2 exactly
• Spawn parallel agents for independent tasks (use --session flags)
• Re-snapshot after every DOM change
• If a cached playbook exists in references/, follow it step-by-step

Worked Example: LinkedIn Profile Automation

Here's the protocol applied to LinkedIn (full playbook: [references/linkedin.md](references/linkedin.md)):

Step 1 result — Research findings:

• Navigation: second "Add profile section" link (first collides with navbar) → dropdown → "Add position"
• Field types: Title=[textbox], Company=[combobox], Employment type=[combobox], Dates=[combobox], Location=[combobox], Description=[contenteditable], Currently working=[checkbox]
• Blockers: "Update to our terms" banner intercepts clicks — dismiss first
• Framework: React SPA — fill works on textbox/combobox, but contenteditable requires eval with innerHTML + InputEvent
• Quirks: Escape triggers "Discard changes?" dialog; Featured link auto-populated title/description breaks if modified via fill

Step 2 result — Execution plan:

• 3 independent tasks → 3 parallel agents:
• --session linkedin-exp: 4 Experience entries (sequential within)
• --session linkedin-skills: 16 Skills (sequential within)
• --session linkedin-feat: 3 Featured links (sequential within)
• Field-to-command mapping per form (see [references/linkedin.md](references/linkedin.md))

Step 3 result: Each agent follows its playbook. ~15min parallel vs ~45min sequential.

After Completion: Cache the Playbook

If this is the first time automating a site, save what you learned as references/.md so future sessions skip Steps 1-2. Include:

• Field type mappings for every form
• Navigation paths to key pages
• Known quirks and anti-patterns
• Parallelization strategy (which tasks are independent)

Command Chaining

Commands can be chained with && in a single shell invocation. The browser persists between commands via a background daemon, so chaining is safe and more efficient than separate calls.

# Chain open + wait + snapshot in one call
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# Chain multiple interactions
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password123" && agent-browser click @e3

# Navigate and capture
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

When to chain: Use && only when you do not need the intermediate output. If a later step depends on snapshot refs or changed DOM state, keep the commands separate.

Essential Commands

# Navigation
agent-browser open               # Navigate (aliases: goto, navigate)
agent-browser close                   # Close browser

# Snapshot
agent-browser snapshot -i             # Interactive elements with refs (recommended)
agent-browser snapshot -i -C          # Include cursor-interactive elements (divs with onclick, cursor:pointer)
agent-browser snapshot -s "#selector" # Scope to CSS selector

# Interaction (use @refs from snapshot)
agent-browser click @e1               # Click element
agent-browser click @e1 --new-tab     # Click and open in new tab
agent-browser fill @e2 "text"         # Clear and type text
agent-browser type @e2 "text"         # Type without clearing
agent-browser select @e1 "option"     # Select dropdown option
agent-browser check @e1               # Check checkbox
agent-browser press Enter             # Press key
agent-browser scroll down 500         # Scroll page

# Get information
agent-browser get text @e1            # Get element text
agent-browser get url                 # Get current URL
agent-browser get title               # Get page title

# Wait
agent-browser wait @e1                # Wait for element
agent-browser wait --load networkidle # Wait for network idle
agent-browser wait --url "**/page"    # Wait for URL pattern
agent-browser wait 2000               # Wait milliseconds

# Capture
agent-browser screenshot              # Screenshot to temp dir
agent-browser screenshot --full       # Full page screenshot
agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
agent-browser pdf output.pdf          # Save as PDF

# Diff (compare page states)
agent-browser diff snapshot                          # Compare current vs last snapshot
agent-browser diff snapshot --baseline before.txt    # Compare current vs saved file
agent-browser diff screenshot --baseline before.png  # Visual pixel diff
agent-browser diff url                   # Compare two pages
agent-browser diff url   --wait-until networkidle  # Custom wait strategy
agent-browser diff url   --selector "#main"  # Scope to element

Complex Web App Forms (React, SPAs, LinkedIn, etc.)

Modern web apps use React/Angular/Vue with custom form controls. Standard fill doesn't always work. Read the snapshot output to identify the field type, then use the right command.

Decision Tree: Which Command for Which Field?

| Snapshot shows | Use | Example | |---|---|---| | [textbox] or [input type="text"] | fill @ref "text" | agent-browser fill @e3 "John" | | [combobox] (dropdown/autocomplete) | select @ref "option text" | agent-browser select @e5 "Full-time" | | [checkbox] | check @ref or uncheck @ref | agent-browser check @e7 | | [contenteditable] or rich text editor | eval with innerHTML + InputEvent | See below | | [select] (native HTML select) | select @ref "option text" | agent-browser select @e2 "March" |

Contenteditable Fields (Rich Text Editors)

Some apps use contenteditable divs (LinkedIn About/Description, Notion, CMS editors). These IGNORE fill and type. Use JavaScript:

# For contenteditable fields — replace SELECTOR with the actual CSS selector
agent-browser eval --stdin ` or combobox list items directly** — Use `select @ref "option"`. Direct clicks on dropdown items fail with "Could not compute box model."

3. **NEVER use `type` when you mean `fill`** — `type` APPENDS text. `fill` CLEARS then types.

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [CalebDane7](https://github.com/CalebDane7)
- **Source:** [CalebDane7/agent-browser](https://github.com/CalebDane7/agent-browser)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.