name: browser-tools
description: Interact with a web browser. Can start a browser, connect to it, evaluate JavaScript, make screenshots, read console logs and let the user select DOM elements. Use when interacting with unknown websites (e.g. scraping or Userscripts) or debugging browser-stuff. Requires uv.

Browser Tools

This skill provides various scripts to interact with a web browser. There is no need to use "sleep" since all scripts will wait automatically. Always change the working directory to the project root before running any script.

Start

Always start Chrome with remote debugging first:

uv run scripts/start.py

Navigate to a web page

uv run scripts/navigate.py https://example.com
# or open a new tab
uv run scripts/navigate.py https://example.com --new

Execute JavaScript

NOTE: Prefer get-html or pick whenever possible to save on token usage.

uv run scripts/evaluate.py "document.querySelectorAll('a').length"
# For multi-line scripts, use STDIN with heredoc
uv run scripts/evaluate.py - <<'EOF'
const elements = document.querySelectorAll('.item');
elements.forEach(el => el.classList.add('processed'));
return elements.length;
EOF
# Or from a file
uv run scripts/evaluate.py path/to/script.js

Pick DOM elements

Use an interactive element picker to instruct the user to pick DOM elements that should be debugged or shown:

uv run scripts/pick.py "Click the submit button"
uv run scripts/pick.py "Select all product cards"

Returns element information including tag, id, class, text content, HTML, and parent hierarchy.

Mouse actions

uv run scripts/mouse.py click "button#submit"
uv run scripts/mouse.py dblclick ".item"
uv run scripts/mouse.py hover "nav .menu-item"
uv run scripts/mouse.py right-click ".context-menu-trigger"
uv run scripts/mouse.py drag ".draggable" --to ".drop-zone"

Fill text fields

uv run scripts/fill.py "input#username" "john_doe"
uv run scripts/fill.py "textarea#comment" "Hello, world!" --clear
uv run scripts/fill.py "input[name='email']" "[email protected]"

Check/uncheck checkboxes

uv run scripts/check.py "input#accept-terms"
uv run scripts/check.py "input[name='newsletter']" --uncheck
uv run scripts/check.py "input[type='radio'][value='option1']"

Press keyboard keys

uv run scripts/press-key.py "Enter"
uv run scripts/press-key.py "Escape"
uv run scripts/press-key.py "a" --selector "input#search"

Upload files

uv run scripts/upload.py "input[type='file']" /path/to/file.pdf
uv run scripts/upload.py "#file-upload" /path/to/image1.jpg /path/to/image2.png

Download files

uv run scripts/download.py "a[href='/report.pdf']"
uv run scripts/download.py "button#download" --output ~/Documents/report.pdf

Select dropdown options

uv run scripts/select-dropdown.py "select#country" "US"
uv run scripts/select-dropdown.py "select[name='color']" "Red" --by-label
uv run scripts/select-dropdown.py "#quantity" "2" --by-index

Cookies

List cookies

uv run scripts/cookies.py

Clear cookies

uv run scripts/clear-cookies.py

Local/Session storage

List storage items

uv run scripts/storage.py

Clear local/session storage

uv run scripts/clear-storage.py

Get console messages

uv run scripts/console.py
uv run scripts/console.py --errors-only

Capture network requests

ALWAYS start this script in a background agent. During this time, you can manually interact with the page to trigger network requests. The script then logs all requests made.

uv run scripts/network.py
uv run scripts/network.py --type fetch --show-body
uv run scripts/network.py --filter "api\\.example\\.com" --show-headers

Get HTML content

Outputs HTML with optional filtering and additional context.

uv run scripts/get-html.py
uv run scripts/get-html.py --filter "<button.*submit.*>"
uv run scripts/get-html.py --filter "data-id=\"\d+\"" --lines 10

Manage tabs

List all open tabs, switch to a specific tab, or close a tab:

uv run scripts/tabs.py
uv run scripts/tabs.py --switch 0
uv run scripts/tabs.py --close 1

More

For detailed API reference, see REFERENCE.md.