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

# Browser

Uses [browser-use](https://github.com/browser-use/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.

```bash
# 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.

```bash
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.

```bash
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
```