browse-pilot

browse-pilot-cli (bp)

Cross-browser automation CLI that controls Firefox, Chrome, and Edge via WebExtension API — no CDP required.

Features

• 🌐 Supports Firefox, Chrome, and Edge
• 🔒 Uses your real browser profile (cookies, login state, history preserved)
• 🚫 No CDP dependency — operates through WebExtension API with strong anti-detection
• 🤖 Native MCP support — integrates directly with Claude Code
• 🐍 Python session — write automation scripts with a browser object
• ⚡ Single Go binary — serves as CLI, WebSocket server, Native Messaging host, and MCP server
• 🌍 12 languages — auto-detects system locale (macOS AppleLocale / LANG)
• 🔌 Plugin Marketplace — install via /plugin marketplace add in Claude Code

📖 繁體中文版: README_ZH_TW.md

Installation

Claude Code Plugin (Recommended)

In Claude Code, run:

/plugin marketplace add SDpower/browse-pilot-cli
/plugin install browse-pilot@browse-pilot-marketplace

This automatically sets up the MCP server. No manual configuration needed.

Manual Installation

Prerequisites

• Go 1.22+
• Node.js 18+ (for extension build & lint)
• Firefox 109+ / Chrome 110+ / Edge 110+

Build from Source

# Install via go install
go install github.com/SDpower/browse-pilot-cli/cmd/bp@latest

# Or build from source
git clone https://github.com/SDpower/browse-pilot-cli.git
cd browse-pilot-cli
make build

Extension Installation

Build the extensions first:

bash scripts/build-extensions.sh

Firefox

1. Open about:debugging
2. Click "This Firefox"
3. Click "Load Temporary Add-on"
4. Select dist/firefox/manifest.json

Chrome

1. Open chrome://extensions
2. Enable "Developer mode" (top right)
3. Click "Load unpacked"
4. Select the dist/chrome/ directory

Edge

1. Open edge://extensions
2. Enable "Developer mode" (left sidebar)
3. Click "Load unpacked"
4. Select the dist/edge/ directory

Native Messaging Host Setup

Chrome and Edge communicate via Native Messaging, which requires host manifest installation:

bp_cli setup firefox
bp_cli setup chrome
bp_cli setup edge

# Or set up all browsers at once
bp_cli setup --all

Quick Start

Check Environment

bp_cli doctor

Basic Operations

# Open a webpage
bp_cli open https://example.com

# Get page state (list all interactive elements)
bp_cli state

# Click an element (by index)
bp_cli click 0

# Type text into a specific field
bp_cli input 1 "hello world"

# Take a screenshot
bp_cli screenshot output.png

Wait & Extract

# Wait for an element
bp_cli wait selector "table.result"

# Wait for text to appear
bp_cli wait text "Loading complete"

# Execute JavaScript
bp_cli eval "document.querySelectorAll('tr').length"

# Get page information
bp_cli get title
bp_cli get html --selector "table"
bp_cli get text 2

Python Automation

# Execute Python code (with access to browser object)
bp_cli python "result = browser.state(); print(len(result['elements']))"

# Execute a Python script
bp_cli python --file script.py

# List session variables
bp_cli python --vars

# Reset session
bp_cli python --reset

Command Reference

Global Flags

Flag	Description	Default
--browser	Target browser (firefox / chrome / edge / auto)	auto
--port	WebSocket port	9222
--json	JSON output format	false
--timeout	Timeout in milliseconds	30000
--verbose	Verbose logging	false
--mcp	Run as MCP server	false
--session	Session name	default
--native-messaging	Run as NM host	false

Navigation

Command	Description
bp_cli open <url>	Navigate to URL
bp_cli back	Go back
bp_cli forward	Go forward
bp_cli reload	Reload page
bp_cli scroll <up|down>	Scroll page (optional --amount <px>)

Page Inspection

Command	Description
bp_cli state	List current URL, title, and all interactive elements
bp_cli screenshot [path]	Take screenshot (outputs base64 if no path; --full for full page)

Interaction