Skip to main content
browser controls a headless browser by running agent-browser CLI commands. It connects to any CDP-compatible browser (such as Lightpanda) over the Chrome DevTools Protocol WebSocket interface. agent-browser maintains its own daemon session between calls, so a navigate in one call and a click in the next operate on the same browser state.

​
Prerequisites

1

Install agent-browser

Install the agent-browser CLI globally on the server where Reacher is deployed:
npm install -g agent-browser
2

Start a CDP-compatible browser

Run a CDP-compatible browser and expose its WebSocket debugger. Lightpanda is a lightweight option:
lightpanda serve --host 127.0.0.1 --port 9222
Any Chromium-based browser launched with --remote-debugging-port=9222 also works.
3

Configure Reacher (optional)

By default Reacher connects to ws://127.0.0.1:9222. Override with environment variables if your browser is on a different host or port:
BROWSER_CDP_HOST=127.0.0.1
BROWSER_CDP_PORT=9222

​
Parameters

​
command
string
required
An agent-browser command string. The tool parses this into arguments respecting quoted strings before passing to the CLI.Supported commands:
  • open <url> — navigate to a URL
  • snapshot -i — take an accessibility/DOM snapshot of the current page
  • click @<elementId> — click an element by its agent-browser element ID
  • fill @<elementId> <value> — fill a form field with a value
  • close — close the current page/session
Example values: "open https://example.com", "snapshot -i", "click @e2", "fill @e3 hello world"

​
Configuration

VariableDefaultDescription
BROWSER_CDP_HOST127.0.0.1Host of the CDP-compatible browser
BROWSER_CDP_PORT9222WebSocket debugger port
The tool connects to ws://<BROWSER_CDP_HOST>:<BROWSER_CDP_PORT> and passes it to agent-browser via the --cdp flag.

​
Return value

​
success
boolean
true if agent-browser exited with code 0.
​
command
string
The command string that was executed.
​
stdout
string
Trimmed standard output from agent-browser. For snapshot, this contains the page’s accessibility tree or DOM representation.
​
stderr
string
Trimmed standard error output. If agent-browser is not installed, this will contain a helpful installation message.
​
exitCode
number
Process exit code from agent-browser. 0 means success.

​
Usage examples

{
  "command": "open https://example.com"
}

​
Common use cases

Scrape a page Navigate to a URL, take a snapshot to see the page structure, then extract the relevant content from stdout. 
1. open https://status.myservice.com
2. snapshot -i
Fill and submit a form Navigate to a page, take a snapshot to discover element IDs, then fill and submit the form. 
1. open https://app.example.com/login
2. snapshot -i          ← read element IDs from output
3. fill @e2 myusername
4. fill @e3 mypassword
5. click @e4            ← submit button
6. snapshot -i          ← verify logged-in state
Take a visual snapshot for monitoring Navigate to a dashboard or status page and snapshot it to check current state as part of an automated check. Automate repetitive web tasks Sequence multiple commands across calls to automate multi-step flows — the agent-browser daemon preserves session state between tool calls.
The agent-browser binary must be installed on the server where Reacher runs, not on the machine Claude is accessed from. If it’s missing, stderr will contain: agent-browser binary not found. Run npm install -g agent-browser on the server where Reacher is deployed.