agent-browser

# Agent Browser

Headless browser automation CLI optimized for AI agents.

## Overview

Agent Browser provides deterministic browser control through accessibility snapshots and refs. Instead of fragile CSS selectors, agents take snapshots to get refs (e.g., `@e2`) that point to exact elements. This snapshot-then-act workflow is optimal for LLM-based automation.

## When to Use

**Use for:**
- Troubleshooting UI issues (visual inspection, element state)
- Testing UI changes before/after comparisons
- Writing bash-based end-to-end tests
- Automating form submissions or multi-step workflows
- Debugging visibility, focus, or interaction problems

**Do NOT use for:**
- API testing (use curl or API tools)
- Non-visual backend operations
- Static file generation
- Tasks that don't require browser rendering

## Quick Reference

| Task | Command |
|------|---------|
| Open page | `agent-browser open <url>` |
| Get elements | `agent-browser snapshot` |
| Click element | `agent-browser click @e2` |
| Fill input | `agent-browser fill @e3 "text"` |
| Get text | `agent-browser get text @e1` |
| Screenshot | `agent-browser screenshot [path]` |
| Wait for element | `agent-browser wait <selector>` |
| Close browser | `agent-browser close` |

## Snapshot-First Pattern

The recommended interaction pattern follows a snapshot-first approach:

1. **Navigate** to the target URL
2. **Snapshot** to get accessibility tree with refs
3. **Identify** target elements from ref output
4. **Interact** using refs (not CSS selectors)
5. **Re-snapshot** after DOM changes

This pattern ensures deterministic element selection and avoids fragile selectors.

## Selectors

### Refs (Recommended)

Refs from snapshots provide deterministic element targeting:

```bash
agent-browser snapshot
# Output: - button "Submit" [ref=e2]
#         - textbox "Email" [ref=e3]

agent-browser click @e2       # Click button
agent-browser fill @e3 "x"    # Fill textbox
```

**Why refs?** Deterministic (exact element from snap