agent-browser

Files (11)

• SKILL.md
• authentication.md · references/
• commands.md · references/
• profiling.md · references/
• proxy-support.md · references/
• session-management.md · references/
• snapshot-refs.md · references/
• video-recording.md · references/
• authenticated-session.sh · templates/
• capture-workflow.sh · templates/
• form-automation.sh · templates/

SKILL.md (first lines)

# Browser Automation with agent-browser

## Core Workflow

Every browser automation follows this pattern:

1. **Navigate**: `agent-browser open <url>`
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

**Version:** targets agent-browser >= 0.15.0 (tested 0.15.2). If your installed `agent-browser --version` is older, run via `npx -y agent-browser@0.15.2 ...` or upgrade.

**Sessions:**

- `--session <name>` = isolated in-memory browser context (parallel work)
- `--session-name <name>` = auto-save/restore state (cookies/storage) across restarts
- Combine both if needed: `agent-browser --session <run> --session-name <persist> ...`

### Login wall handling (choose method)

If you hit a login wall (SSO/2FA/CAPTCHA, forced redirect to `/login`, auth modal, etc.), **pause and ask the user which login method they want** (use the `ask_user` tool; do not ask for passwords in chat).

Options:

- **Manual (headed) login** (recommended for SSO/2FA/CAPTCHA)
- **Auth profile (automated) login** (built-in `agent-browser auth`, for simple username/password flows)

After login (either method): **persist the authenticated session/state** and then resume the **original user goal**.

#### Path A — Manual (headed) login

1. **Open headed + isolate session** (so auth can be reused):

   ```bash
   agent-browser --headed --session-name <site> open <login-url>
   ```

2. **Ask user to complete login** in the visible browser window.

3. **Persist the session** (pick one):
   - Auto (recommended):

     ```bash
     agent-browser close  # auto-saves state for --session-name <site>
     ```

   - Explicit file (portable):

     ```bash
     agent-browser state save <site>-auth.json
     ```

4. **Proceed with original goal** using the same saved session/state:

   ```bash
   agent-browser --session-name <site> open <target-url>
   # or: agent-browser state load <site>-auth.json && agent-browser open <target-url>
   ```

#### Path B — Auth profile (automated) login

1. Create an auth profile once (built-in encrypted credential store; never ask user for password in chat):
   ```bash
   echo "<pass>" | agent-browser auth save <site> --url <login-url> --username <user> --password-stdin
   ```
2. Login using the saved profile:
   ```bash
   agent-browser auth login <site>
   ```
3. Persist state (pick one):
   - Auto: ensure you ran with `--session-name <site>` and then `agent-browser close`.
   - Explicit file: `agent-browser state save <site>-auth.json`
4. If you hit SSO/2FA/CAPTCHA or automation fails, **fall back to Path A** (headed manual login) and persist state.

Notes:

- If you started headless and discover a login wall, `close` and re-`open` with `--headed` for Path A.
- Keep the original goal in scope; login is only an enabling step.

```bash
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 "<password-from-vault>"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i  # Check result
```

## 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.

```bash
# 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 "$PASSWORD" && 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 `&&` when you don't need to read the output of an intermediate command before proceeding (e.g., open + wait + screenshot). Run commands separately when you need to parse the output first (e.g., snapshot to discover refs, then interact using those refs).

## Essential Commands

```bash
# Navigation
agent-browser open <url>              # 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)

From siarhei-belavus/agent-public, MIT.

More from siarhei-belavus/agent-public