Browser Agent Bridge CLI

SKILL.md

---
name: browser-bridge-cli
description: Use this skill when you need to control or make actions on the user's chrome tab.
---

# Browser Bridge CLI

## When to use

Use this skill when you need to control a real Chrome tab. Typical situations:
- browser automation with live user browser context
- page observation (interactive elements and DOM snapshots)
- remote tab actions (navigate, click, type, press_key, scroll)
- troubleshooting connection state between agent and browser

Project:
- https://github.com/NmadeleiDev/browser_agent_bridge

## What this gives you

This workflow has three connected parts:
- Browser extension in Chrome receives tab commands.
- Bridge server routes messages between browser and operator.
- Operator CLI sends commands and reads results.

CLI commands used:
- `browser-bridge-server` to run the server
- `browser-bridge` to run operator actions

## Prerequisites

- Python 3.10+
- Chrome browser
- Terminal access
- Ability to load an unpacked Chrome extension

## Agent responsibility before startup

Before starting the server, generate strong tokens. Do not use weak defaults.

Example token generation:

```bash
python3 - <<'PY'
import secrets
print("BRIDGE_SHARED_TOKEN=" + secrets.token_urlsafe(32))
print("BRIDGE_OPERATOR_TOKEN=" + secrets.token_urlsafe(32))
PY
```

Use generated values when starting the server. Share only the client token (`BRIDGE_SHARED_TOKEN`) with the user for extension setup. Keep operator token for agent CLI usage.

## Install the CLI

```bash
python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install browser-agent-bridge
```

Upgrade later:

```bash
pipx upgrade browser-agent-bridge
```

## Start the bridge server

Use static auth for straightforward local setup:

```bash
export BRIDGE_AUTH_MODE=static
export BRIDGE_SHARED_TOKEN='change-me-strong-token'
export BRIDGE_OPERATOR_TOKEN='Str0ng!Operator#42'
browser-bridge-server >/tmp/browser-bridge-server.log 2>&1 &
echo $! >/tmp/browser-bridge-server.pid
```

Start `browser-bridge-server` in the background. Do not leave it attached to the current shell, because the agent needs that shell for follow-up CLI commands, status checks, and diagnostics. If startup needs verification, inspect the log file or process state after backgrounding it.

Default endpoints:
- Extension client WS: `ws://127.0.0.1:8765/ws/client`
- Operator CLI WS: `ws://127.0.0.1:8765/ws/operator`

## Connect the Chrome extension (tell your human to do this)

1. Open `chrome://extensions`.
2. Enable `Developer mode`.
3. Click `Load unpacked`.
4. Select the extension provided by this project from https://github.com/NmadeleiDev/browser_agent_bridge (`extension/` folder).
5. Open the Browser Bridge extension popup.
6. Fill fields:
- `Bridge Server WS URL`: `ws://127.0.0.1:8765/ws/client`
- `Instance ID`: `local-instance`
- `Client ID`: `chrome-main`
- `Auth Token / JWT`: value of `BRIDGE_SHARED_TOKEN` generated by the agent
7. Click `Save`, then `Connect`.
8. Confirm popup status is connected to the server started by the agent.

## Operator CLI usage

All examples use:
- `instance_id=local-instance`
- `client_id=chrome-main`
- operator token `Str0ng!Operator#42`
- operator websocket `ws://127.0.0.1:8765/ws/operator`

You can pass the operator token either with `--token` or by exporting `BRIDGE_OPERATOR_TOKEN`. The examples below use `--token` explicitly for clarity.

List connected browser clients:

```bash
browser-bridge --server-ws-url ws://127.0.0.1:8765/ws/operator --token 'Str0ng!Operator#42' list-clients
```

Check whether the specific client is connected:

```bash
browser-bridge --server-ws-url ws://127.0.0.1:8765/ws/operator --token 'Str0ng!Operator#42' \
  connect-status --instance-id local-instance --client-id chrome-main
```

Check whether tab command channel is ready:

```bash
browser-bridge --server-ws-url ws://127.0.0.1:8765/ws/operator --token 'Str0ng!Operator#42' \
  ping-tab --instance-id local-instance --client-id chrome-main
```

Observe interactive nodes on current page:

```bash
browser-bridge --server-ws-url ws://127.0.0.1:8765/ws/operator --token 'Str0ng!Operator#42' \
  observe --instance-id local-instance --client-id chrome-main --max-nodes 150
```

Get page HTML snapshot:

```bash
browser-bridge --server-ws-url ws://127.0.0.1:8765/ws/operator --token 'Str0ng!Operator#42' \
  send-command --instance-id local-instance --client-id chrome-main \
  --type get_html --payload '{"max_chars":40000}'
```

Navigate with adaptive load wait:

```bash
browser-bridge --server-ws-url ws://127.0.0.1:8765/ws/operator --token 'Str0ng!Operator#42' \
  send-command --instance-id local-instance --client-id chrome-main \
  --type navigate --payload '{"url":"https://example.com","wait_for_load":true,"wait_for_load_ms":7000}'
```

Click without load wait:

```bash
browser-bridge --server-ws-url ws://127.0.0.1:8765/ws/operator --token 'Str0ng!Operator#42' \
  send-command --instance-id local-instance --client-id chrome-main \
  --type click --payload '{"selector":"a[href]","wait_for_load":false}'
```

Type into an element:

```bash
browser-bridge --server-ws-url ws://127.0.0.1:8765/ws/operator --token 'Str0ng!Operator#42' \
  send-command --instance-id local-instance --client-id chrome-main \
  --type type --payload '{"selector":"input[name=q]","text":"browser bridge"}'
```

Press a special key:

```bash
browser-bridge --server-ws-url ws://127.0.0.1:8765/ws/operator --token 'Str0ng!Operator#42' \
  send-command --instance-id local-instance --client-id chrome-main \
  --type press_key --payload '{"key":"Enter","selector":"input[name=q]"}'
```

`press_key` supports:
- keys: `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Home`, `End`, `PageUp`, `PageDown`, `Space`
- aliases: `return`, `esc`, `del`, `up`, `down`, `left`, `right`, `spacebar`
- modifiers: `alt_key`, `ctrl_key`, `meta_key`, `shift_key`
- target selection via `selector`, `ref`, `click_ref`, or `locator`
- default target: current `document.activeElement` when no selector/ref is provided

## Recommended execution flow for agents

1. Ensure server process is running.
2. Ensure extension popup is connected with matching `instance_id`, `client_id`, and token.
3. Run `list-clients`.
4. Run `connect-status`.
5. Run `ping-tab`.
6. Run `observe` before action commands.
7. Run `send-command` actions (`navigate`, `click`, `type`, `press_key`, `scroll`, `get_html`).
8. Re-run `observe` to confirm page state after actions.

## Troubleshooting

- `Target client not connected`
  - Verify popup shows connected.
  - Verify `instance_id` and `client_id` exactly match CLI flags.
  - Reconnect extension and retry.

- `Operator auth failed` or auth errors
  - Verify `--token` matches `BRIDGE_OPERATOR_TOKEN`.

- `Command timed out`
  - Increase `--timeout-s`.
  - For action commands, disable or reduce load wait in payload.
  - Confirm active tab is a normal webpage (not restricted pages like `chrome://*`).

- `Receiving end does not exist`
  - Retry once; extension can reinject content script when needed.

- Slow responses on action commands
  - Use `wait_for_load=false` for immediate response.
  - Or set smaller `wait_for_load_ms`.

## Security notes

- Treat tokens as secrets.
- For non-local deployments, use TLS (`wss://`) and strong secrets.

## Done criteria

1. `list-clients` returns expected client.
2. `connect-status` is connected.
3. `ping-tab` reports ready.
4. `observe` returns page data.
5. `send-command` actions return valid results.