@amaster.ai/pi-browser-use

pi-coding-agent extension that wraps chrome-devtools-mcp, exposing all browser automation tools with a unified browser_ prefix.

Features

• pi-coding-agent extension — registers tools via pi.registerTool(), managed by the agent lifecycle
• Dynamic tool discovery — automatically proxies all upstream chrome-devtools-mcp tools with browser_ prefix
• Reproducible MCP runtime — launches the installed chrome-devtools-mcp entrypoint with the current Node executable instead of downloading @latest through ambient npx
• Page-scoped routing — routes page tools by explicit pageId instead of shared selected-page state
• Connection recovery — detects closed or unhealthy MCP transports and reconnects before the next call
• Navigation safety — supports URL allow/block patterns and redacts sensitive network headers by default
• Tool description augmentation — adds usage hints for key tools (click, fill, press_key, etc.)
• Result post-processing — strips embedded snapshots, detects overlay/stale element issues
• Optional visual analysis — browser_analyze_screenshot via configurable vision model
• Standalone mode — also runnable as an independent MCP server via CLI

Install

bun add @amaster.ai/pi-browser-use

Requires Node.js ^20.19.0 || ^22.12.0 || >=23, Chrome (stable or newer), and @earendil-works/pi-coding-agent >= 0.74.0.

chrome-devtools-mcp is a compatible runtime dependency and its installed entrypoint is resolved when the extension module loads. A missing or malformed installation fails extension loading immediately; the extension does not download a replacement at connection time. Connection failures expose only allowlisted system error codes or Chrome startup categories, not raw subprocess stderr.

Hosts where process.execPath is not a directly executable Node runtime can set PI_BROWSER_USE_NODE to the Node command used for the MCP subprocess.

Usage

As pi-coding-agent Extension (Recommended)

Install the package and pi-coding-agent will automatically discover and load the extension. All browser tools are registered on session_start.

bun add @amaster.ai/pi-browser-use

Configure via .pi/settings.json (project-level) or ~/.pi/agent/settings.json (user-level) under the "pi-browser-use" key:

Project settings are loaded only after project trust is accepted. ${ENV_VAR} interpolation is supported in user and agent settings, but not in project settings.

{
  "pi-browser-use": {
    "headless": true,
    "channel": "stable",
    "viewport": "1280x720",
    "experimentalVision": true,
    "blockedUrlPattern": ["https://ads.example/*"]
  }
}

As Standalone MCP Server (CLI)

npx @amaster.ai/pi-browser-use --headless --viewport=1280x720

Or with a config file:

npx @amaster.ai/pi-browser-use --config path/to/config.json

Configuration

Session Mode

Mode	Description
persistent (default)	Reuses a shared browser profile at ~/.pi/browser-profile. Cookies, logins, and extensions persist across sessions.
isolated	Launches a fresh ephemeral browser profile each session. No state carried over.
existing	Connects to an already-running browser instance (via browserUrl, wsEndpoint, or auto-discovery).

Note: Do not run the agent (or anything that launches this browser) via sudo — the profile would be created with root-owned files, and Chrome then shows a "can't read your preferences" dialog on every launch. On startup the extension detects an inaccessible default profile, moves it aside to ~/.pi/browser-profile.inaccessible-<timestamp>, and starts fresh; a custom userDataDir in this state fails fast with an ownership remediation hint instead.

{
  "pi-browser-use": {
    "sessionMode": "persistent"
  }
}

Browser

Option	Type	Default	Description
headless	boolean	false	Run browser in headless mode
channel	string	—	Chrome channel: canary, dev, beta, stable
browserUrl	string	—	Connect to existing browser via URL
wsEndpoint	string	—	Connect via WebSocket endpoint
executablePath	string	—	Path to Chrome executable
viewport	string	—	Viewport size, e.g. 1280x720
isolated	boolean	false	Use isolated browser profile
userDataDir	string	—	Custom user data directory
autoConnect	boolean	false	Auto-connect to running browser
acceptInsecureCerts	boolean	false	Ignore invalid or self-signed certificate errors; use with caution

Categories

Option	Type	Default	Description
categoryPerformance	boolean	false	Enable performance tools
categoryNetwork	boolean	true	Enable network tools
categoryEmulation	boolean	true	Enable emulation tools
categoryExtensions	boolean	false	Enable extension tools

Experimental

Option	Type	Default	Description
experimentalVision	boolean	true	Enable vision tools (click_at)
experimentalScreencast	boolean	false	Enable screencast
experimentalMemory	boolean	false	Enable memory snapshots
experimentalPageIdRouting	boolean	true	Add a required pageId to page-scoped tools and route directly to that page

Privacy

Option	Type	Default	Description
usageStatistics	boolean	false	Send usage statistics
performanceCrux	boolean	false	Enable CrUX performance data
redactNetworkHeaders	boolean	true	Redact sensitive headers in network tool results
allowedUrlPattern	string[]	—	Allow only matching URLPattern values; requires Chrome 149+
blockedUrlPattern	string[]	—	Block matching navigation and subresource URLPattern values

allowedUrlPattern and blockedUrlPattern are mutually exclusive. Page ID routing is disabled automatically in slim mode because upstream slim tools do not expose pageId.

Page-scoped Tool Calls

With the default page ID routing enabled, call browser_list_pages first and pass the returned numeric page ID to subsequent page-scoped tools:

browser_list_pages({})
browser_take_snapshot({ "pageId": 2 })
browser_click({ "pageId": 2, "uid": "12_4" })
browser_take_screenshot({ "pageId": 2 })

This avoids relying on browser_select_page when multiple browser calls or tabs are active. A single chrome-devtools-mcp process still serializes tool execution; page ID routing provides isolation rather than parallel throughput.

Vision Model (Optional)

Enable browser_analyze_screenshot by referencing a model already configured in Pi's model registry (models.json):

{
  "pi-browser-use": {
    "visionModel": {
      "provider": "openai",
      "model": "gpt-4o"
    }
  }
}

The extension resolves API key, base URL, and headers from the model registry automatically — no need to duplicate credentials here.

With the default page ID routing enabled, visual analysis also targets a page explicitly:

browser_analyze_screenshot({ "pageId": 2, "instruction": "Find the blue submit button" })

Tool Augmentation

Key tools receive additional usage hints in their descriptions:

Tool	Hint
browser_click	Use element uid from snapshot; UIDs invalidated after action
browser_fill	Does not work on canvas/custom widgets
browser_press_key	Accepts single key name only
browser_take_snapshot	Call first to get uids, and after every state-changing action
browser_navigate_page	Call take_snapshot after navigation

Result Post-Processing

• Snapshot stripping — Removes embedded accessibility tree snapshots from non-snapshot tool responses to prevent token bloat
• Overlay detection — When a click is blocked by an overlay/popup, appends a hint to dismiss it first
• Stale element detection — When element references are stale, appends a hint to refresh the snapshot

Excluded Tools

• lighthouse_audit — Filtered out at the proxy level

License

Apache-2.0