Browser Agent Bridge CLI

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:

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

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:

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.