---
name: browser-use
description: Control the Agentastic built-in browser. Use when asked to open a webpage, check a UI, test a form, verify frontend changes, take a screenshot, inspect elements, or interact with a running web application.
allowed-tools: Bash(dev browser *)
---

You have access to a built-in browser inside Agentastic via `dev browser` commands. Use this to navigate websites, inspect the DOM, interact with elements, and verify UI changes.

## Prerequisites

The environment variables `AGENTASTIC_SOCKET_PATH` and optionally `AGENTASTIC_BROWSER_ID` are set automatically in Agentastic terminals. If `AGENTASTIC_SOCKET_PATH` is not set, tell the user to run the command from an Agentastic terminal.

## Core Workflow

### 1. Open or navigate to a page

```bash
# Open a URL in a new browser tab (returns the browser_id)
dev browser open "http://localhost:3000"

# Or navigate the current tab
dev browser navigate "http://localhost:3000"

# Wait for the page to finish loading
dev browser wait load
```

### 2. Snapshot the page

Always snapshot before interacting. This returns an accessibility tree with `@eN` references:

```bash
dev browser snapshot
```

Output looks like:
```
heading 'Dashboard' @e1
  navigation 'Main'
    link 'Home' @e2
    link 'Settings' @e3
  textbox 'Search...' @e4
  button 'Save' @e5
```

### 3. Interact with elements

Use `@eN` references from the snapshot (preferred) or CSS selectors:

```bash
dev browser click "@e5"
dev browser fill "@e4" "search query"
dev browser type "@e4" "typed text"     # character-by-character
dev browser press "@e4" "Enter"
dev browser check "@e6"
dev browser select "#country" "US"
```

### 4. Verify results

```bash
dev browser get title
dev browser get text ".result"
dev browser is visible ".success-message"
dev browser console errors              # check for JS errors
dev browser errors list                 # check for uncaught exceptions
```

### 5. Wait for async updates

```bash
dev browser wait selector ".loaded"
dev browser wait text "Success"
dev browser wait url "/dashboard"
dev browser wait load
```

All wait commands accept `--timeout <ms>`.

## Command Reference

### Navigation
| Command | Description |
|---------|-------------|
| `navigate <url>` | Go to URL |
| `back` | Browser back |
| `forward` | Browser forward |
| `reload` | Reload page |

### Inspection
| Command | Description |
|---------|-------------|
| `snapshot` | DOM accessibility tree with @eN refs |
| `screenshot` | Capture page as base64 PNG |
| `screenshot -o <file>` | Save screenshot to file |
| `highlight <sel>` | Flash a red outline on an element |

### Actions
| Command | Description |
|---------|-------------|
| `click <sel>` | Click element |
| `dblclick <sel>` | Double-click |
| `fill <sel> <value>` | Clear + set value (React-safe) |
| `type <sel> <text>` | Type character by character |
| `press <sel> <key>` | Press a key (Enter, Tab, etc.) |
| `keydown <sel> <key>` | Dispatch keydown event only |
| `keyup <sel> <key>` | Dispatch keyup event only |
| `hover <sel>` | Hover over element |
| `focus <sel>` | Focus element |
| `check <sel>` | Check checkbox |
| `uncheck <sel>` | Uncheck checkbox |
| `select <sel> <value>` | Select dropdown option |
| `scroll <x> <y> [sel]` | Scroll by pixels |
| `scroll_into_view <sel>` | Scroll element into view |
| `eval <js>` | Evaluate JavaScript |
| `focus_webview` | Make browser first responder |
| `is_webview_focused` | Check if browser is focused |

### Wait
| Command | Description |
|---------|-------------|
| `wait selector <sel>` | Wait for element to appear |
| `wait text <text>` | Wait for text on page |
| `wait url <pattern>` | Wait for URL to contain pattern |
| `wait load` | Wait for page load complete |

### Query
| Command | Description |
|---------|-------------|
| `get url` | Current URL |
| `get title` | Page title |
| `get text [sel]` | Text content |
| `get html [sel]` | HTML content |
| `get value <sel>` | Input value |
| `get attr <sel> <attr>` | HTML attribute |
| `get count <sel>` | Count matching elements |
| `get box <sel>` | Bounding box |
| `get styles <sel> <props>` | Computed CSS (comma-separated) |
| `is visible <sel>` | Visibility check |
| `is enabled <sel>` | Enabled check |
| `is checked <sel>` | Checked check |

### Console / Errors
| Command | Description |
|---------|-------------|
| `console list` | All console messages |
| `console errors` | Only console errors |
| `console clear` | Clear console messages |
| `errors list` | List uncaught JS errors (window.onerror, unhandledrejection) |

### Find
| Command | Description |
|---------|-------------|
| `find role <role>` | By ARIA role |
| `find text <text>` | By text content |
| `find label <label>` | By label |
| `find placeholder <text>` | By placeholder |
| `find testid <id>` | By data-testid |
| `find alt <alt>` | By alt attribute |
| `find title <title>` | By title attribute |
| `find first <selector>` | First element matching selector |
| `find last <selector>` | Last element matching selector |
| `find nth <selector> <n>` | Nth element matching selector (0-indexed) |

### Tabs
| Command | Description |
|---------|-------------|
| `list` | List all browser tabs |
| `open <url>` | Open new tab |
| `open_split <url>` | Open in split |
| `close [id]` | Close tab |
| `focus_tab <id>` | Switch to tab |
| `tab new <url>` | Open new tab (alias) |
| `tab list` | List tabs (alias) |
| `tab switch <id>` | Switch tab (alias) |
| `tab close [id]` | Close tab (alias) |

### Dialogs
| Command | Description |
|---------|-------------|
| `dialog accept [text]` | Accept a JS dialog (alert/confirm/prompt). Optional text for prompt. |
| `dialog dismiss` | Dismiss a JS dialog (cancel confirm/prompt). |

Call `dialog accept` or `dialog dismiss` **before** triggering the dialog to pre-configure the response automatically. Or call it **after** if a dialog is already pending.

### Cookies
| Command | Description |
|---------|-------------|
| `cookies get [--name n] [--domain d]` | Get cookies (optionally filtered) |
| `cookies set <name> <value> [--domain d] [--path p]` | Set a cookie |
| `cookies clear [--name n] [--domain d]` | Clear cookies |

### Storage
| Command | Description |
|---------|-------------|
| `storage get <local\|session> [key]` | Get storage value(s) |
| `storage set <local\|session> <key> <value>` | Set a storage value |
| `storage clear <local\|session> [key]` | Clear storage (all or one key) |

### State Persistence
| Command | Description |
|---------|-------------|
| `state save <path>` | Save cookies + storage + URL to JSON file |
| `state load <path>` | Restore browser state from JSON file |

### Frames (iframes)
| Command | Description |
|---------|-------------|
| `frame select <selector>` | Target an iframe (subsequent commands run inside it) |
| `frame main` | Return to the main frame |

Only works with same-origin iframes.

### Downloads
| Command | Description |
|---------|-------------|
| `download wait <path> [--timeout <ms>]` | Wait for a file to appear at path |

### Script / Style Injection
| Command | Description |
|---------|-------------|
| `addinitscript <js>` | Add JS that runs at document start on every page load |
| `addscript <js>` | Evaluate JS immediately |
| `addstyle <css>` | Inject a CSS stylesheet |

### System
| Command | Description |
|---------|-------------|
| `ping` | Health check |
| `identify` | Instance info |
| `capabilities` | List methods |

## Important Rules

1. **Always snapshot before interacting.** You need `@eN` refs to target elements.
2. **Always `wait load` after navigation.** Pages need time to render.
3. **Use `fill` for form inputs, not `type`.** `fill` is faster and works with React controlled inputs. Use `type` only when you need keypress events.
4. **Refs reset on each snapshot.** `@e5` from a previous snapshot may point to a different element after a new snapshot.
5. **Use `--browser-id`** when working with multiple tabs. Get IDs from `dev browser list`.
6. **Check `console errors`** after interactions to catch JavaScript failures.
7. **Use `wait` commands** instead of sleeping. They poll efficiently and fail on timeout.
8. **Pre-configure dialogs** before triggering them. Call `dialog accept` before clicking a button that shows a `confirm()`.
9. **Use `frame select`** before interacting with iframe content. Call `frame main` to return.