---

name: browser description: remotely orchestrate a (chromium) browser to utilize web apps

Browser

Uses browser-use (via Chrome DevTools Protocol) to browse any website. Remotely orchestrate a browser, to navigate the web. Meaning any task that can be accomplished via a browser.

Instructions

• read README.md to understand this project

QUICK REFERENCE

These are CLI commands you may use.

| Task | Command | Purpose | |------|---------|---------| | Start Browser Server | browser server start | Start background browser server | | Stop Browser Server | browser server stop | Stop background server | | Server Status | browser server status | Check server status and latest logs summary | | View Live Logs | browser server logs --follow | Tail live server logs | | Get Page Status | browser client status | Get current page URL and title | | Navigate to URL | browser client navigate URL | Navigate browser to specified URL | | Execute JavaScript | browser client execute JAVASCRIPT | Execute JavaScript code (arrow function) | | Get DOM Content | browser client dom [SELECTOR] | Get HTML content of element (default: body) | | Fill Input Field | browser client fill SELECTOR VALUE | Fill form input field with value | | Click Element | browser client click SELECTOR | Click on specified element | | Click at Coordinates | browser client click-at X Y | Click at specific coordinates | | Get Cookies | browser client cookies [--domain D] [--name N] | Read cookies incl. HttpOnly (CDP) | | Authed XHR | browser client xhr URL [-X METHOD] [-H 'K: V'] [-d BODY] [--body] | Run a request inside the page's origin (carries cookies, bypasses CORS) | | SSO Login + Capture | browser login --url URL --match '*host/path*' [--cookie NAME] [--local KEY] [--eval NAME=JS] [--out FILE] | Headed SSO login; capture cookies / localStorage / eval values. No SSO provider is hardcoded — you pass --match globs (or --success-url regex). | | Start Capture | browser capture start [FILE] [--filter SUBSTR] | Record HTTP + WebSocket traffic to NDJSON | | Stop Capture | browser capture stop | Stop the active capture | | Verify/Repair CLI | browser-agent doctor | Ensure the browser command is THIS CLI (repairs browser-use shadowing) |

Examples

Sample user prompt:

let's test this project:

• start browser service
• use client scripts to
  • navigate to google.com
  • type hamster dance into search box
  • click search button
  • read first 3 search results
  • summarize them in your response to me
  • stop the server

Sample agent output (ie. Gemini 3 Flash):

GitHub Copilot: Created 6 todos

Starting: *Start browser service* (1/6)

Ran terminal command: browser server start

Stdout:
Starting browser server...
✅ Server started in background (PID 12345)
Logs: /home/user/.browser_agent/server.log

Starting: *Navigate to Google* (2/6)

Ran terminal command: browser client navigate "https://www.google.com"

Stdout:
✅ Navigated to https://www.google.com

Starting: *Type search query* (3/6)

Ran terminal command: browser client fill "[name='q']" "hamster dance"

Stdout:
✅ Filled [name='q']

Starting: *Click search button* (4/6)

Ran terminal command: browser client click "[name='btnK']"

Stdout:
✅ Clicked [name='btnK']

Starting: *Read search results* (5/6)

Ran terminal command: browser client execute "() => Array.from(document.querySelectorAll('#search h3')).slice(0, 3).map(h3 => ({title: h3.innerText, link: h3.closest('a')?.href}))"

Stdout:
Result: [{"title": "Hampton the Hamster \"The Hamsterdance Song\"", "link": "https://www.youtube.com/watch?v=1qN72LEQnaU"}, ...]

Starting: *Stop server* (6/6)

Ran terminal command: browser server stop

Stdout:
✅ Server stopped (PID 12345)

Completed: *Summarize results*

The browser service was successfully started, and I performed the requested search for "hamster dance" on Google. Here are the first three search results:

1.  **Hampton the Hamster "The Hamsterdance Song"**
    - [https://www.youtube.com/watch?v=1qN72LEQnaU](https://www.youtube.com/watch?v=1qN72LEQnaU)
2.  **Hampton the Hamster - The Hamsterdance Song (Official Video ...**
    - [https://www.youtube.com/watch?v=6WpMlwVwydo](https://www.youtube.com/watch?v=6WpMlwVwydo)
3.  **Hamster Dance - Wikipedia**
    - [https://en.wikipedia.org/wiki/Hamster_Dance](https://en.wikipedia.org/wiki/Hamster_Dance)

SSO Login + Cookie Capture Example

Open a headed browser, let the user complete SSO (e.g. Okta), and capture the session cookie(s) once the page settles. Reusable by any tool that needs a cookie-authenticated session.

# Capture the Slack 'd' cookie after login, writing JSON to a file
browser login \
  --url https://app.slack.com/client \
  --cookie d \
  --cookie-domain slack.com \
  --success-url "/client" \
  --out ./.cookies.json
# Detection is staged: URL must match --success-url (or destination host),
# the page must finish loading, and all required --cookie names must be present
# before capture. Without --out, the cookie map prints to stdout.

Authenticated XHR Example

Run an HTTP request from inside the current page's origin — it carries existing cookies and bypasses CORS. Useful for hitting same-site JSON endpoints.

browser client navigate "https://app.example.com"
browser client xhr "https://app.example.com/api/me" --body
# --body prints only the response body; omit it to see status + headers + body
browser client xhr "https://app.example.com/api/items" -X POST \
  -H 'Content-Type: application/json' -d '{"q":"x"}'

Traffic Capture Example

Record HTTP requests/responses and WebSocket frames (via CDP) to NDJSON for reverse-engineering an API.

browser capture start --filter example.com      # only record matching URLs
browser client navigate "https://example.com"   # interact / click around
browser capture stop                             # flush + close the file
# Output: captures/<timestamp>.ndjson, one JSON record per request/response/ws frame