Skill: nmadeleidev/browser-agent-bridge-cli (version 1.0.4)

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


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)