browser

Category: Tools & Productivity | Uploader: lidge-jun | Downloads: 0 | Version: v1.0（Latest）
Chrome browser control: open pages, take ref snapshots, click, type, screenshot. No external server required.
Changelog: Source: GitHub https://github.com/lidge-jun/agbrowse
Directory Structure

Current level: tree/main/skills/browser/
📄 browser-core.mjs 2.0 KB
📄 browser.mjs 83.6 KB
📄 profile-lock.mjs 4.1 KB
📄 skill-install.mjs 10.0 KB
📄 SKILL.md 10.0 KB
📄 tab-lifecycle.mjs 7.0 KB
📄 tab-manager.mjs 12.2 KB
📄 tab-monitor.mjs 3.2 KB
SKILL.md

---
name: browser
description: "Chrome browser control: open pages, take ref snapshots, click, type, screenshot. No external server required."
---

# Browser Control

Control Chrome browser via `agbrowse` commands.
Uses ref-based snapshots to identify page elements, then click/type by ref ID.

## Prerequisites

- Node.js 18+
- Google Chrome (or Chromium/Brave) installed
- `playwright-core` installed:

```bash
cd <project-root>
npm install playwright-core
```

## Quick Start

```bash
agbrowse start                               # Start Chrome (CDP auto port)
agbrowse start --headless                    # Headless mode (server/CI/WSL)
agbrowse navigate "https://example.com"      # Go to URL
agbrowse snapshot --interactive              # Interactive elements with ref IDs
agbrowse click e3                            # Click ref e3
agbrowse type e5 "hello" --submit           # Type + Enter
agbrowse screenshot                          # Save screenshot
agbrowse reload                              # Reload current page
```

For AI provider websites, use the bundled `web-ai` skill/command instead of
raw click/type sequences when possible:

```bash
agbrowse web-ai status --vendor chatgpt
agbrowse web-ai query --vendor gemini --url https://gemini.google.com/app --inline-only --prompt "Reply exactly OK"
```

## Core Workflow

> **Always follow this pattern:**
> 1. `snapshot --interactive` → See elements + ref IDs
> 2. `click`/`type`/`press`/`select` → Interact using ref
> 3. `snapshot` → Verify result → Repeat

## Commands

### Browser Management

```bash
agbrowse start [--port <9222>] [--headless|--headed] [--chrome-path /path/to/chrome]
agbrowse stop
agbrowse status
agbrowse reset [--force]
```

### Observe

```bash
agbrowse snapshot                # Ref snapshot (all elements)
agbrowse snapshot --interactive  # Interactive elements only (recommended)
agbrowse snapshot --max-nodes 30 # Limit output for token budget
agbrowse screenshot              # Current viewport
agbrowse screenshot --full-page  # Full page
agbrowse screenshot --ref e5     # Specific ref element only
agbrowse screenshot --clip 0 0 320 180  # Clipped region in CSS pixels
agbrowse screenshot --json       # JSON output (path, dpr, viewport)
agbrowse text                    # Page text content
agbrowse text --format html      # HTML source
agbrowse get-dom                 # Full DOM HTML
agbrowse get-dom --selector ".card" --max-chars 2000
agbrowse console --clear --reload --duration 3000 # Buffered console logs
agbrowse network --reload --duration 1000         # Fresh page-load + async requests
```

### Snapshot Output Example

```
e1   link       "Gmail"
e2   link       "Images"
e3   textbox    "Search"           ← To type here: type e3 "query"
e4   button     "Google Search"    ← To click: click e4
e5   button     "I'm Feeling Lucky"
```

### Act

```bash
agbrowse click e3              # Click element
agbrowse click e3 --double     # Double-click
agbrowse click e3 --right      # Right-click / context menu
agbrowse type e3 "hello"       # Type text
agbrowse type e3 "hello" --submit  # Type + press Enter
agbrowse press Enter           # Press key
agbrowse press Escape
agbrowse press Tab
agbrowse hover e5              # Mouse hover
agbrowse select e7 "option1"   # Select dropdown option
agbrowse drag e3 e5            # Drag element to another
agbrowse move-mouse 400 300    # Move mouse only
agbrowse mouse-down            # Hold left mouse button
agbrowse mouse-up --right      # Release right mouse button
agbrowse mouse-click 400 300   # Click at pixel coordinates
```

### Navigate & Scroll

```bash
agbrowse navigate "https://example.com"  # Go to URL
agbrowse reload                           # Reload current page
agbrowse resize 1440 900                 # Resize browser window
agbrowse resize 0 0 --fullscreen         # Fullscreen or 1920x1080 viewport fallback
agbrowse tabs                             # List tabs
agbrowse tab-switch 2                     # Switch to tab 2
agbrowse scroll down                      # Scroll down 500px
agbrowse scroll up --amount 1000          # Scroll up 1000px
agbrowse scroll --ref e15                 # Scroll element into view
agbrowse evaluate "document.title"        # Execute JS
```

### Wait & Sync

```bash
agbrowse wait 2000              # Wait 2 seconds
agbrowse wait-for e5            # Deprecated: wait for last-snapshot ref
agbrowse wait-for-selector ".toast-success" --timeout 30000
agbrowse wait-for-text "Dashboard" --timeout 30000
```

## Common Workflows

### Web Search

```bash
agbrowse start
agbrowse navigate "https://www.google.com"
agbrowse snapshot --interactive
# → e3 textbox "Search"
agbrowse type e3 "search query" --submit
agbrowse snapshot --interactive
# Click desired result link
agbrowse click e7
```

### Form Filling

```bash
agbrowse snapshot --interactive
# → e1 textbox "Name", e2 textbox "Email", e3 button "Submit"
agbrowse type e1 "John Doe"
agbrowse type e2 "john@example.com"
agbrowse click e3
agbrowse snapshot  # Verify result
```

### SPA Login Flow

```bash
agbrowse navigate "https://app.example.com/login"
agbrowse snapshot --interactive
agbrowse type e1 "user@example.com"
agbrowse type e2 "password"
agbrowse click e3                    # Login button
agbrowse wait-for-text "Dashboard" --timeout 15000
agbrowse snapshot --interactive      # Verify logged in
```

### Long Page with Scrolling

```bash
agbrowse navigate "https://news.ycombinator.com"
agbrowse snapshot --interactive --max-nodes 20  # First 20 items
agbrowse scroll down
agbrowse snapshot --interactive --max-nodes 20  # Next items
```

### Multi-Tab Workflow

```bash
agbrowse navigate "https://docs.example.com"  # Tab 1
agbrowse evaluate "window.open('https://api.example.com')"  # Tab 2
agbrowse tabs                  # List tabs
agbrowse tab-switch 2          # Switch to tab 2
agbrowse snapshot --interactive
```

### Inspect DOM / Console / Network

```bash
agbrowse navigate "https://example.com"
agbrowse get-dom --selector "main" --max-chars 4000
agbrowse console --clear --expression "console.log('probe')"
agbrowse network --reload --duration 2000 --filter example
```

## Recovery Strategy

If something goes wrong, follow this escalation path:

1. **`snapshot` fails** → Try `screenshot` for visual inspection
2. **Ref not found** → Re-run `snapshot --interactive` (refs reset on navigation and can go stale after page changes)
3. **CDP connection fails** → `status`, then `start` if Chrome is not running
4. **Chrome frozen** → ask before `reset --force`; reset deletes local browser state
5. **Fullscreen resize falls back in headless mode** → The command uses a 1920x1080 viewport fallback when window APIs are unavailable
6. **DOM ref unavailable** (Canvas/WebGL/Shadow DOM) → Use `vision-click` skill after confirming no usable ref exists

## Environment Variables

| Variable             | Default            | Description                               |
| -------------------- | ------------------ | ----------------------------------------- |
| `BROWSER_AGENT_HOME` | `~/.browser-agent` | Data directory (profile, screenshots)     |
| `CDP_PORT`           | `9222`             | Default Chrome DevTools Protocol port     |
| `CHROME_HEADLESS`    | `0`                | Set to `1` for headless mode; `start --headed` overrides it |
| `CHROME_NO_SANDBOX`  | `0`                | Set to `1` to disable sandbox (Docker/CI) |
| `CHROME_BINARY_PATH` | auto-detect        | Override Chrome/Chromium executable path  |

## Headless Mode (Server/CI/WSL)

```bash
agbrowse start --headless               # CLI flag
CHROME_HEADLESS=1 agbrowse start         # env var
CHROME_HEADLESS=1 agbrowse start --headed  # force a visible headed Chrome
```

- GUI 없는 환경(WSL, SSH, Docker, CI)에서 사용
- `--headless=new` (Chrome 112+) 사용 — full browser 기능 유지

## Troubleshooting

| Symptom                          | Cause                               | Fix                                            |
| -------------------------------- | ----------------------------------- | ---------------------------------------------- |
| CDP connection refused           | Chrome running with default profile | Close all Chrome, retry or `browser.mjs reset` |
| Windows: only test browser opens | Chrome singleton absorbs launch     | Close all Chrome → `browser.mjs start`         |
| Headless CDP not opening         | `--headless` not specified          | Add `--headless` flag                          |
| Port conflict                    | Other process on CDP port           | Use `--port <other>`                           |
| Fullscreen resize falls back     | Headless / unsupported window APIs  | Expected: command switches to a 1920x1080 viewport fallback |
| Snapshot returns many nodes      | Large page, token waste             | Use `--interactive --max-nodes 30`             |

## Notes

- Ref IDs come from the **last snapshot** and reset on navigation. Always re-run `snapshot` after `navigate`, `reload`, tab switches, or any action that changed the page.
- Prefer `wait-for-selector` or `wait-for-text` for async UI state. `wait-for <ref>` only works against the last persisted snapshot and is deprecated.
- Use `--interactive` to show only clickable/typeable elements (shorter list).
- Use `--max-nodes N` to cap output for token budget.
- Screenshots are saved to `~/.browser-agent/screenshots/`.
- Default CDP port is `9222`. Override with `--port` or `CDP_PORT` env var.
- `start --chrome-path /path/to/chrome` and `CHROME_BINARY_PATH` both override auto-detection.
- If CDP is already responding on the port, `start` reuses the existing instance.
- CDP reconnection uses exponential backoff (1s → 2s → 4s → 8s).
- `console` reads a page-side buffer. Use `--clear` before a flow and `--reload` if you want logs from a fresh navigation.
- `network` merges current page performance entries with optional live CDP capture. Use `--duration 0` for a fast current-state dump only, add a non-zero duration with `--reload` if the page triggers late `fetch`/XHR activity, and use `--live-only` to skip performance history.
- Non-DOM elements (Canvas, iframe, Shadow DOM): use **vision-click** skill.
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
browser

Directory Structure

SKILL.md

Report

Notice
