---
name: browser-tools
description: Use this skill when the user asks to test, verify, interact with, or automate web pages and browsers. Trigger for requests involving Chrome automation, browser testing, web scraping, screenshot capture, element selection, or checking web applications. Also trigger when user mentions "browser tools" explicitly.
allowed-tools: Bash(browser-start:*), Bash(browser-nav:*), Bash(browser-eval:*), Bash(browser-screenshot:*), Bash(browser-pick:*), Bash(browser-cookies:*), Read, Read(/tmp/screenshot*), Glob
---

# Browser Tools

Chrome DevTools Protocol automation for agent-assisted web testing and interaction. Uses Chrome running on `:9222` with remote debugging.

## Prerequisites

**Run `/browser-tools:setup` once after plugin installation** - This installs dependencies and creates global symlinks for all browser scripts.

## Usage

When user asks to test, verify, or interact with web pages using browser tools:

1. **Start Chrome** - Launch with debugging enabled
2. **Navigate & interact** - Use scripts to navigate, evaluate JS, take screenshots
3. **Return results** - Show output/screenshots to user

**IMPORTANT**: Use command names directly (e.g., `browser-start`), NOT full paths (e.g., `~/bin/browser-start`). Commands are in PATH after setup.

## Available Scripts

All scripts located in `skills/browser-tools/scripts/`:

### browser-start

By default use the persistent profile at `/tmp/chrome-profile-browser-tools`.

```bash
browser-start --profile    # Persistent profile
browser-start              # Fresh profile
```

Launch Chrome with remote debugging on port 9222. Use `--profile` to maintain login state between sessions.

### browser-nav

```bash
browser-nav https://example.com
browser-nav https://example.com --new
```

Navigate to URLs. Use `--new` to open in new tab instead of current tab.

### browser-eval

```bash
browser-eval 'document.title'
browser-eval 'document.querySelectorAll("a").length'
browser-eval 'Array.from(document.querySelectorAll("h1")).map(h => h.textContent)'
```

Execute JavaScript in active tab. Runs in async context. Use for:

- Extract data from pages
- Inspect page state
- Manipulate DOM
- Test page functionality

### browser-screenshot

```bash
browser-screenshot
```

Capture current viewport, returns temp file path. Use Read tool to show screenshot to user.

### browser-pick

```bash
browser-pick                      # Uses default message "Select element(s)"
browser-pick "Select the submit button"
```

**Interactive element picker** - Launches UI overlay for user to click and select elements. Returns element details (tag, id, class, text, html, parent hierarchy). Message parameter is optional.

Use when:

- User says "click that button" or "extract those items"
- Need specific selectors but page structure is unclear
- User wants to identify elements visually

Controls:

- Click to select single element
- Cmd/Ctrl+Click for multiple selections
- Enter to finish (when multiple selected)
- ESC to cancel

### browser-cookies

```bash
browser-cookies
```

Display all cookies for current tab (domain, path, httpOnly, secure flags). Use for debugging auth issues.

## Workflow Examples

### Test dev server feature

```bash
# Start browser with persistent profile
browser-start --profile

# Navigate to dev server
browser-nav http://localhost:3000

# Test functionality
browser-eval 'document.querySelector("#new-feature").textContent'

# Take screenshot
SCREENSHOT=$(browser-screenshot)
# Then use Read tool to show screenshot at $SCREENSHOT path
```

### Debug authentication

```bash
browser-start --profile
browser-nav https://app.example.com/login
browser-cookies
```

### Extract data from page

```bash
browser-start
browser-nav https://example.com
browser-eval 'Array.from(document.querySelectorAll(".product")).map(p => ({name: p.querySelector(".title").textContent, price: p.querySelector(".price").textContent}))'
```

## Important Notes

- **Chrome must be installed** - Scripts use `google-chrome` binary
- **Port 9222** - Chrome runs with `--remote-debugging-port=9222`
- **Profile location** - `/tmp/chrome-profile-browser-tools` when using `--profile`
- **Temp screenshots** - Screenshots saved to OS temp directory
- **Dependencies** - Requires `chrome-remote-interface` (installed via `/browser-tools:setup`)
- **Error handling** - If scripts fail, check Chrome is running and port 9222 is available