@monoes/monomindcli 1.10.28 → 1.10.30

package/.claude/skills/monomind/browse.md

@@ -0,0 +1,724 @@
+---
+name: monomind:browse
+description: State-of-the-art browser automation skill for UI testing, web scraping, and agent-driven navigation using agent-browser (v0.27+). Token-optimized with ref-based element selection, batch execution, KV-cache prompt ordering, on-demand screenshots, and full monomind memory integration.
+version: 2.0.0
+triggers:
+  - /browse
+  - monomind:browse
+  - browse the web
+  - test the UI
+  - browser automation
+  - open the browser
+  - navigate to
+  - click on the website
+  - fill out the form
+  - test login
+  - take a screenshot
+  - check the page
+  - web vitals
+  - react tree
+  - scrape
+  - crawl
+tools:
+  - Bash
+requires:
+  - agent-browser >= 0.25.4
+---
+
+# monomind:browse
+
+State-of-the-art browser automation using agent-browser. Optimized for minimal token consumption, maximum test coverage, and deep monomind integration.
+
+---
+
+## Setup (Run Once)
+
+```bash
+# Install
+npm install -g agent-browser
+
+# Download Chrome (first time only)
+agent-browser install
+
+# Verify
+agent-browser --version   # should be >= 0.25.4
+agent-browser doctor      # check all systems
+```
+
+---
+
+## Token Efficiency Rules (ALWAYS FOLLOW)
+
+These rules are non-negotiable. Violating them wastes tokens and degrades performance.
+
+1. **Batch multi-step flows** — Use `agent-browser batch` to execute sequences in a single process invocation. Eliminates per-command startup overhead.
+2. **Snapshot with `-i` flag** — Interactive-only snapshots are 93% smaller than full trees. Never call `agent-browser snapshot` without `-i` unless you need to understand full page structure.
+3. **Reuse refs** — After a snapshot, refs (`@e1`, `@e2`) are stable for the current page. Do NOT re-snapshot unless the page changed. One snapshot per page-state.
+4. **On-demand screenshots only** — Screenshots add ~800ms and ~1500 tokens as images. Only call `agent-browser screenshot` when: element not in a11y tree, visual verification is required, or the task explicitly needs visual proof.
+5. **Use batch for read-only chains** — `agent-browser open url && agent-browser snapshot -i` is two process starts. `agent-browser batch "open url" "snapshot -i"` is one.
+6. **Scope snapshots** — When testing a form or component, use `agent-browser snapshot -i -s "#form-id"` to scope to that subtree only.
+7. **Prefer `wait --text` over polling** — Never sleep and re-snapshot. Use `agent-browser wait --text "Expected"` or `wait --url "**pattern"`.
+
+---
+
+## Core Loop
+
+```
+OPEN → SNAPSHOT -i → ACT (by ref) → SNAPSHOT -i (if page changed) → VERIFY → REPEAT
+```
+
+### Minimal golden-path example
+
+```bash
+# Batch: open + snapshot in one call
+agent-browser batch "open https://app.example.com/login" "snapshot -i"
+# → snapshot output: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Sign In" [ref=e3]
+
+agent-browser fill @e1 "user@test.com"
+agent-browser fill @e2 "SecurePass123!"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard" --timeout 8000
+
+# Re-snapshot only because URL changed (new page state)
+agent-browser snapshot -i
+```
+
+### Full batch mode (most token-efficient)
+
+```bash
+agent-browser batch \
+  "open https://app.example.com/login" \
+  "snapshot -i" \
+  "fill @e1 user@test.com" \
+  "fill @e2 SecurePass123!" \
+  "click @e3" \
+  "wait --url **/dashboard" \
+  "snapshot -i"
+```
+
+Or as JSON via stdin (best for programmatic use):
+
+```bash
+echo '[
+  ["open", "https://app.example.com/login"],
+  ["snapshot", "-i"],
+  ["fill", "@e1", "user@test.com"],
+  ["fill", "@e2", "SecurePass123!"],
+  ["click", "@e3"],
+  ["wait", "--url", "**/dashboard"],
+  ["snapshot", "-i"]
+]' | agent-browser batch --json --bail
+```
+
+---
+
+## All Commands Reference
+
+### Navigation
+
+```bash
+agent-browser open <url>              # Launch + navigate (aliases: goto, navigate)
+agent-browser open                    # Launch on about:blank (for pre-nav setup)
+agent-browser back                    # Go back
+agent-browser forward                 # Go forward
+agent-browser reload                  # Reload
+agent-browser pushstate <url>         # SPA client-side nav (Next.js, Remix, etc.)
+agent-browser close                   # Close browser
+agent-browser close --all             # Close all sessions
+```
+
+### Snapshot (primary observation tool)
+
+```bash
+agent-browser snapshot                # Full accessibility tree + refs
+agent-browser snapshot -i             # Interactive elements only (USE THIS BY DEFAULT)
+agent-browser snapshot -i --urls      # Include href URLs for links
+agent-browser snapshot -c             # Compact (strip empty structural nodes)
+agent-browser snapshot -d 3           # Limit depth to 3 levels
+agent-browser snapshot -s "#main"     # Scope to CSS selector
+agent-browser snapshot -i -c -d 5    # Combined: compact interactive, max depth 5
+agent-browser snapshot --json         # JSON output for programmatic use
+```
+
+**Output example:**
+```
+- textbox "Email" [ref=e1]
+- textbox "Password" [ref=e2]
+- button "Sign In" [ref=e3]
+- link "Forgot password" [ref=e4]
+```
+
+### Interaction
+
+```bash
+# Primary: use @ref from snapshot (fastest, no DOM re-query)
+agent-browser click @e3
+agent-browser fill @e1 "value"
+agent-browser dblclick @e5
+agent-browser hover @e6
+agent-browser check @e7               # checkbox
+agent-browser uncheck @e8
+agent-browser select @e9 "Option A"
+agent-browser focus @e2
+
+# Keyboard
+agent-browser press Enter
+agent-browser press Tab
+agent-browser press "Control+a"
+agent-browser keyboard type "hello world"      # real keystrokes
+agent-browser keyboard inserttext "hello"      # insert without key events
+agent-browser keydown Shift
+agent-browser keyup Shift
+
+# Drag & drop
+agent-browser drag @e1 @e2
+agent-browser upload @e3 /path/to/file.pdf
+
+# Scroll
+agent-browser scroll down 500         # scroll 500px down
+agent-browser scroll up
+agent-browser scrollintoview @e10
+agent-browser scroll down --selector "#feed"
+```
+
+### Semantic locators (fallback when no ref available)
+
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "test@test.com"
+agent-browser find placeholder "Search..." fill "query"
+agent-browser find testid "submit-btn" click
+agent-browser find first ".item" click
+agent-browser find nth 2 "a" text
+```
+
+### Wait (never sleep/poll manually)
+
+```bash
+agent-browser wait 500                         # ms delay (use sparingly)
+agent-browser wait "#spinner" --state hidden   # wait for element to hide
+agent-browser wait --text "Success"            # wait for text to appear
+agent-browser wait --url "**/dashboard"        # wait for URL pattern
+agent-browser wait --load networkidle          # wait for network idle
+agent-browser wait --fn "window.ready === true"  # wait for JS condition
+agent-browser wait --fn "!document.body.innerText.includes('Loading')"
+```
+
+### Read state
+
+```bash
+agent-browser get text @e1           # text content
+agent-browser get html @e2           # innerHTML
+agent-browser get value @e3          # input value
+agent-browser get attr @e4 "href"    # attribute
+agent-browser get title              # page title
+agent-browser get url                # current URL
+agent-browser get count ".item"      # count matching elements
+agent-browser get box @e1            # bounding box
+agent-browser get styles @e1         # computed CSS styles
+
+agent-browser is visible @e1         # boolean check
+agent-browser is enabled @e1
+agent-browser is checked @e1
+```
+
+### Screenshots (use sparingly)
+
+```bash
+agent-browser screenshot                        # auto-path in /tmp
+agent-browser screenshot page.png              # specific path
+agent-browser screenshot --full full-page.png  # full-page scroll capture
+agent-browser screenshot --annotate            # numbered refs overlaid → use with visual models
+agent-browser pdf report.pdf                   # save as PDF
+```
+
+**Annotated screenshot pattern** (for visual debugging or multimodal LLMs):
+```bash
+agent-browser screenshot --annotate
+# Output: [1] @e1 button "Submit"  [2] @e2 link "Home"  [3] @e3 textbox "Email"
+# Now refs are cached — interact immediately without re-snapshot
+agent-browser click @e1
+```
+
+### Diff (regression testing)
+
+```bash
+agent-browser diff snapshot                           # current vs last snapshot
+agent-browser diff snapshot --baseline ./before.txt   # vs saved file
+agent-browser diff snapshot -s "#main" --compact      # scoped diff
+agent-browser diff screenshot --baseline before.png   # pixel diff
+agent-browser diff screenshot --baseline b.png -t 0.2 # threshold 0–1
+agent-browser diff url https://v1.com https://v2.com  # compare two URLs
+agent-browser diff url https://v1.com https://v2.com --screenshot  # + visual
+```
+
+### Tabs & multi-tab
+
+```bash
+agent-browser tab                          # list all tabs
+agent-browser tab new https://example.com  # new tab
+agent-browser tab new --label docs https://docs.example.com  # named tab
+agent-browser tab docs                     # switch by label
+agent-browser tab t2                       # switch by stable id
+agent-browser tab close docs               # close by label
+agent-browser window new                   # new window
+agent-browser frame "#iframe-id"           # switch to iframe
+agent-browser frame main                   # back to main frame
+```
+
+**Multi-tab parallel test pattern:**
+```bash
+agent-browser tab new --label app https://app.example.com
+agent-browser tab new --label docs https://docs.example.com
+agent-browser tab app
+agent-browser snapshot -i    # refs for app tab
+agent-browser click @e3
+agent-browser tab docs
+agent-browser snapshot -i    # refs for docs tab
+```
+
+### Dialogs
+
+```bash
+agent-browser dialog accept "confirmation text"
+agent-browser dialog dismiss
+agent-browser dialog status            # is a dialog currently open?
+```
+
+Note: `alert` and `beforeunload` are auto-accepted by default. `confirm` and `prompt` need explicit handling.
+
+### Network interception
+
+```bash
+agent-browser network route "https://api.example.com/*" --abort    # block endpoint
+agent-browser network route "*" --abort --resource-type script      # block all JS
+agent-browser network route "https://api/*" --body '{"data":[]}'   # mock response
+agent-browser network unroute "https://api.example.com/*"
+agent-browser network requests                          # view tracked requests
+agent-browser network requests --filter api             # filter by URL substring
+agent-browser network requests --type xhr,fetch         # filter by type
+agent-browser network requests --method POST
+agent-browser network requests --status 2xx
+agent-browser network request <requestId>               # full request/response
+agent-browser network har start                         # record HAR
+agent-browser network har stop output.har               # stop + save
+```
+
+**Pre-nav setup pattern** (set network routes BEFORE navigating):
+```bash
+agent-browser batch \
+  '["open"]' \
+  '["network", "route", "*", "--abort", "--resource-type", "script"]' \
+  '["cookies", "set", "--curl", "auth.curl", "--domain", "localhost"]' \
+  '["navigate", "http://localhost:3000"]'
+```
+
+### Cookies & storage
+
+```bash
+agent-browser cookies                              # get all cookies
+agent-browser cookies set name value              # set cookie
+agent-browser cookies set --curl cookies.curl     # import from cURL dump / JSON / header string
+agent-browser cookies clear
+
+agent-browser storage local                        # get localStorage
+agent-browser storage local myKey                  # get specific key
+agent-browser storage local set myKey myValue      # set
+agent-browser storage local clear
+agent-browser storage session                      # sessionStorage (same API)
+```
+
+### Browser settings
+
+```bash
+agent-browser set viewport 1280 720 2             # width height deviceScaleFactor
+agent-browser set device "iPhone 15 Pro"          # device emulation
+agent-browser set geo 37.7749 -122.4194           # geolocation
+agent-browser set offline on                      # offline mode
+agent-browser set headers '{"Authorization":"Bearer tok"}'  # global headers
+agent-browser set credentials user pass           # HTTP basic auth
+agent-browser set media dark                      # color scheme
+```
+
+### Clipboard
+
+```bash
+agent-browser clipboard read
+agent-browser clipboard write "Hello"
+agent-browser clipboard copy      # Ctrl+C
+agent-browser clipboard paste     # Ctrl+V
+```
+
+### Mouse (raw control, use only when refs/semantic locators fail)
+
+```bash
+agent-browser mouse move 100 200
+agent-browser mouse down left
+agent-browser mouse up left
+agent-browser mouse wheel 100 0   # dy dx
+```
+
+### React DevTools (v0.27+)
+
+Requires launching with `--enable react-devtools`:
+
+```bash
+# Launch with hook installed
+agent-browser open --enable react-devtools https://your-react-app.com
+
+# Inspect component tree
+agent-browser react tree                         # full component hierarchy
+agent-browser react inspect 5                    # fiber ID → props, hooks, state, source
+agent-browser react renders start                # begin render profiling
+agent-browser react renders stop                 # print profile (mount/re-render counts)
+agent-browser react renders stop --json          # JSON output
+agent-browser react suspense                     # Suspense boundaries + root-cause classifier
+agent-browser react suspense --only-dynamic      # hide static boundaries
+```
+
+### Web Vitals (framework-agnostic)
+
+```bash
+agent-browser vitals                             # LCP, CLS, TTFB, FCP, INP + React hydration
+agent-browser vitals https://example.com         # test specific URL
+agent-browser vitals --json                      # JSON output
+```
+
+### Tracing & profiling
+
+```bash
+agent-browser trace start trace.zip             # start Chrome trace
+agent-browser trace stop trace.zip              # stop and save
+agent-browser profiler start                    # DevTools profiler
+agent-browser profiler stop profile.json        # stop and save
+
+agent-browser console                           # browser console messages
+agent-browser console --json                    # structured CDP output
+agent-browser console --clear
+agent-browser errors                            # uncaught JS exceptions
+agent-browser errors --clear
+```
+
+### Sessions & auth
+
+```bash
+# Isolated sessions (each has own browser, cookies, history)
+agent-browser --session agent1 open site-a.com
+agent-browser --session agent2 open site-b.com
+agent-browser session list
+
+# Persist state across restarts
+agent-browser --session-name myapp open app.example.com
+# → auto-saves to ~/.agent-browser/sessions/myapp
+
+# Reuse existing Chrome login
+agent-browser profiles                          # list Chrome profiles
+agent-browser --profile Default open gmail.com
+
+# Save / load state
+agent-browser state save ./auth.json            # save cookies + localStorage
+agent-browser state load ./auth.json
+agent-browser --state ./auth.json open https://app.example.com/dashboard
+
+# Auth vault (credentials never sent to LLM)
+echo "mypassword" | agent-browser auth save github --url https://github.com/login --username me --password-stdin
+agent-browser auth login github
+
+# Encrypted state at rest
+export AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex>
+agent-browser --session-name secure open example.com
+```
+
+### Dashboard (observability)
+
+```bash
+agent-browser dashboard start              # port 4848
+agent-browser dashboard start --port 8080
+agent-browser dashboard stop
+# → open http://localhost:4848 for live viewport + activity feed + AI chat
+```
+
+### Init scripts
+
+```bash
+agent-browser open --init-script ./setup.js https://app.example.com
+agent-browser addinitscript "window.__TEST__ = true"
+agent-browser removeinitscript <identifier>
+```
+
+### iOS / Mobile (real Safari)
+
+Requires: `npm install -g appium && appium driver install xcuitest`
+
+```bash
+agent-browser device list
+agent-browser -p ios --device "iPhone 15 Pro" open https://example.com
+agent-browser -p ios snapshot -i
+agent-browser -p ios tap @e1
+agent-browser -p ios fill @e2 "text"
+agent-browser -p ios swipe up
+agent-browser -p ios screenshot mobile.png
+agent-browser -p ios close
+```
+
+### Cloud providers
+
+| Provider | Env var | Flag |
+|---------|---------|------|
+| Browserbase | `BROWSERBASE_API_KEY` | `-p browserbase` |
+| Browser Use | `BROWSER_USE_API_KEY` | `-p browseruse` |
+| Browserless | `BROWSERLESS_API_KEY` | `-p browserless` |
+| Kernel | `KERNEL_API_KEY` | `-p kernel` |
+| AWS AgentCore | AWS credentials | `-p agentcore` |
+
+All commands work identically regardless of provider.
+
+### Streaming
+
+```bash
+agent-browser stream status           # see WebSocket port
+agent-browser stream enable --port 9223
+agent-browser stream disable
+```
+
+### CDP / Electron apps
+
+```bash
+agent-browser connect 9222            # connect to port, persist for session
+agent-browser --cdp 9222 snapshot     # per-command
+agent-browser --cdp wss://remote/cdp snapshot
+agent-browser --auto-connect snapshot  # auto-discover running Chrome
+```
+
+---
+
+## Test Flows
+
+### Login / Auth
+
+```bash
+agent-browser batch \
+  "open https://app.example.com/login" \
+  "snapshot -i"
+# identify refs from output, then:
+agent-browser fill @e[email] "user@test.com"
+agent-browser fill @e[password] "TestPass123!"
+agent-browser click @e[submit]
+agent-browser wait --url "**/dashboard" --timeout 8000
+```
+
+### Form with validation
+
+```bash
+# Test happy path
+agent-browser batch "open /form" "snapshot -i"
+agent-browser fill @e1 "John Doe"
+agent-browser fill @e2 "john@test.com"
+agent-browser select @e3 "Option A"
+agent-browser check @e4
+agent-browser click @e5
+agent-browser wait --text "submitted"
+agent-browser screenshot pass-form.png
+
+# Test validation (empty submit)
+agent-browser reload
+agent-browser snapshot -i
+agent-browser click @e5                    # submit empty
+agent-browser wait --text "required"
+agent-browser snapshot -i                  # verify error messages
+
+# Invalid email
+agent-browser fill @e2 "not-an-email"
+agent-browser click @e5
+agent-browser snapshot -i
+```
+
+### CRUD
+
+```bash
+# Create
+agent-browser click @e[add]
+agent-browser fill @e[name] "New Item"
+agent-browser click @e[save]
+agent-browser wait --text "New Item"
+
+# Update
+agent-browser click @e[edit]
+agent-browser fill @e[name] "Updated Item"
+agent-browser click @e[save]
+agent-browser wait --text "Updated Item"
+
+# Delete
+agent-browser click @e[delete]
+agent-browser wait --text "Are you sure"
+agent-browser click @e[confirm]
+agent-browser wait --fn "!document.body.innerText.includes('Updated Item')"
+```
+
+### Multi-step wizard
+
+```bash
+# Step 1
+agent-browser batch "open /wizard" "snapshot -i"
+agent-browser fill @e1 "value"
+agent-browser click @e[next]
+agent-browser wait --text "Step 2"
+
+# Step 2
+agent-browser snapshot -i
+agent-browser select @e2 "choice"
+agent-browser click @e[next]
+
+# Step 3 — verify summary
+agent-browser snapshot -i
+agent-browser get text @e[summary]
+agent-browser click @e[confirm]
+agent-browser wait --text "Complete"
+```
+
+### Regression test (diff baseline)
+
+```bash
+# Save baseline
+agent-browser open https://app.example.com
+agent-browser snapshot -i > baseline.txt
+
+# After a deploy, compare:
+agent-browser open https://app.example.com
+agent-browser diff snapshot --baseline ./baseline.txt
+```
+
+### API mocking
+
+```bash
+# Mock API response, test UI reaction
+agent-browser batch \
+  '["open"]' \
+  '["network", "route", "https://api.example.com/users", "--body", "{\"data\":[]}"]' \
+  '["navigate", "https://app.example.com/users"]'
+agent-browser snapshot -i
+# → verify "No users found" empty state renders correctly
+```
+
+### React app deep inspection
+
+```bash
+agent-browser open --enable react-devtools https://your-react-app.com
+agent-browser react tree
+agent-browser vitals --json
+agent-browser react renders start
+# ... trigger user interactions ...
+agent-browser react renders stop
+agent-browser react suspense --only-dynamic
+```
+
+---
+
+## Configuration (agent-browser.json)
+
+Create in project root for persistent defaults:
+
+```json
+{
+  "$schema": "https://agent-browser.dev/schema.json",
+  "maxOutput": 50000,
+  "contentBoundaries": true,
+  "idleTimeout": "5m",
+  "screenshotDir": "./screenshots",
+  "screenshotFormat": "jpeg",
+  "screenshotQuality": 80
+}
+```
+
+Key security defaults for agent deployments:
+```json
+{
+  "contentBoundaries": true,
+  "maxOutput": 50000,
+  "allowedDomains": ["app.example.com", "*.example.com"],
+  "noAutoDialog": false
+}
+```
+
+Key env vars:
+```bash
+AGENT_BROWSER_SESSION=<name>          # session isolation
+AGENT_BROWSER_SESSION_NAME=<name>     # auto-persist state
+AGENT_BROWSER_MAX_OUTPUT=50000        # prevent context flooding
+AGENT_BROWSER_DEFAULT_TIMEOUT=30000  # op timeout in ms (default: 25000)
+AGENT_BROWSER_IDLE_TIMEOUT_MS=300000  # daemon auto-shutdown after idle
+AGENT_BROWSER_CONTENT_BOUNDARIES=1   # LLM-safe output delimiters
+AGENT_BROWSER_HEADED=1               # visible browser (debugging)
+AGENT_BROWSER_STREAM_PORT=9223       # fixed WebSocket stream port
+AI_GATEWAY_API_KEY=gw_...            # for `agent-browser chat`
+AI_GATEWAY_MODEL=anthropic/claude-sonnet-4-6
+```
+
+---
+
+## Monomind Integration
+
+### Store successful test flows
+
+```bash
+npx monomind memory store \
+  --namespace browse \
+  --key "login-flow-<app>" \
+  --value "open /login → snapshot -i → fill @e[email] → fill @e[pw] → click @e[submit] → wait **/dashboard"
+```
+
+### Retrieve before testing
+
+```bash
+npx monomind memory search --query "login flow" --namespace browse
+```
+
+### Report bugs as tasks
+
+```bash
+npx monomind task create \
+  --title "UI Bug: form submits with empty email" \
+  --description "Steps: open /login, click submit without filling email. No validation shown. Screenshot: /tmp/bug-123.png"
+```
+
+### Save auth state for reuse across sessions
+
+```bash
+# Once logged in:
+agent-browser state save .monomind/auth/<app>.json
+
+# Future sessions:
+agent-browser --state .monomind/auth/<app>.json open https://app.example.com
+```
+
+---
+
+## Anti-patterns (NEVER DO)
+
+| Anti-pattern | Why | Fix |
+|---|---|---|
+| `agent-browser snapshot` (no `-i`) for every step | Full tree = 10–20x tokens | Use `snapshot -i` always |
+| Playwright MCP | 13,700-token schema tax before step 1 | Use agent-browser directly |
+| Screenshot every step | +800ms +1500 tokens each | Screenshot only on fail/visual-required |
+| Re-snapshot without page change | Wastes tokens | Reuse refs from last snapshot |
+| `sleep N` between actions | Slow, fragile | Use `wait --text`, `wait --url`, `wait --fn` |
+| CSS selectors when refs available | Slower, can break | Always prefer `@eN` refs from snapshot |
+| Separate commands when batch works | Extra process starts | Use `batch` for multi-step flows |
+
+---
+
+## Checklist
+
+When this skill is activated:
+- [ ] `agent-browser --version` — confirm >= 0.25.4 (or run `npm install -g agent-browser`)
+- [ ] `agent-browser doctor` — check Chrome + daemon health
+- [ ] Get target URL from user if not provided
+- [ ] Use `batch "open <url>" "snapshot -i"` to start
+- [ ] Use refs (`@eN`) from snapshot output for all interactions
+- [ ] Only re-snapshot after confirmed page-state change
+- [ ] Only screenshot when visual evidence is required
+- [ ] Use `wait --text / --url / --fn` instead of sleep or polling
+- [ ] Report results: ✓ PASS / ✗ FAIL (steps to reproduce) / ⚠ WARN
+- [ ] Store successful patterns in monomind memory (`browse` namespace)
+- [ ] Create monomind task for any found bugs