Browser Bridge CLI

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:

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

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

Upgrade later:

pipx upgrade browser-agent-bridge

Start the bridge server

Use static auth for straightforward local setup:

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

List connected browser clients:

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:

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:

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:

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:

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:

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:

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:

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:

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.