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:
- Start Chrome - Launch with debugging enabled
- Navigate & interact - Use scripts to navigate, evaluate JS, take screenshots
- 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 ${CLAUDE_SKILL_DIR}/scripts/:
browser-start
By default use the persistent profile at /tmp/chrome-profile-browser-tools.
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
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
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
browser-screenshot
Capture current viewport, returns temp file path. Use Read tool to show screenshot to user.
browser-pick
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-console
browser-console # Stream logs until Ctrl+C or kill
browser-console --url http://... # Navigate and exit after load
browser-console --url http://... --no-exit # Navigate then keep streaming
browser-console --level error,warn # Filter by log level
Capture console logs (log, warn, error, info, debug) from Chrome. Includes stack traces for errors and page errors.
Modes:
- Streaming (default): Captures logs until process is killed. Best for workflow monitoring.
- Navigation (
--url): Navigates to URL and exits after page load. Captures logs during page initialization.
Claude Code usage:
# Page load logs - auto-exits after load
browser-console --url http://localhost:3000
# Workflow monitoring - run in background, kill when done
browser-console &
browser-nav http://localhost:3000
browser-eval "triggerSomeAction()"
# Check logs via BashOutput, kill via KillShell
browser-cookies
browser-cookies
Display all cookies for current tab (domain, path, httpOnly, secure flags). Use for debugging auth issues.
Workflow Examples
Test dev server feature
# 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
browser-start --profile
browser-nav https://app.example.com/login
browser-cookies
Extract data from page
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 required - 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