Firefox Agent Bridge

Bridge a WebSocket-connected AI agent to a live Firefox profile via a WebExtension and native messaging host.

Architecture

┌─────────────┐     WebSocket      ┌──────────────────┐     Native Messaging     ┌─────────────────┐
│   Agent     │◄──────────────────►│   Rust Host      │◄───────────────────────►│ Firefox Extension│
│ (CLI/SDK)   │   ws://127.0.0.1   │ (830KB binary)   │    stdin/stdout JSON    │   (JS required)  │
└─────────────┘       :8766        └──────────────────┘                         └─────────────────┘

• Agent connects to the local WebSocket server
• Rust native host forwards commands to the Firefox extension
• Extension executes browser actions and returns results

The entire bridge is written in Rust except for the browser extension (browsers only support JavaScript extensions).

Installation

1. Install the Firefox Extension

Download the signed extension from GitHub Releases:

1. Download browser-agent-bridge-X.X.X.xpi
2. In Firefox, go to about:addons
3. Click gear icon → "Install Add-on From File..."
4. Select the downloaded XPI

2. Build and Install the Native Host (Rust)

# Build the Rust binaries
cd rust-cli
cargo build --release

# Install native messaging manifest
cd ..
./scripts/install-native-host.sh

Windows support

Windows is supported for the core Firefox bridge flow when both release binaries are installed:

• browser-windows-x64.exe - CLI client
• host-windows-x64.exe - Firefox native messaging host

Firefox still requires a native messaging host manifest registered under
HKCU\Software\Mozilla\NativeMessagingHosts\firefox_agent_bridge. Downstream installers such as
jcode browser setup can stage the host binary, write the manifest, and create this registry entry.

Known limitation: persistent browser session ... mode currently uses Unix-domain sockets and is
disabled on Windows. Direct one-shot browser commands and the native messaging host are expected to
compile and run on Windows.

3. Install the CLI

# Install globally via cargo
cargo install --path rust-cli

# For Claude Code users - install the skill
browser setup claude

Alternative: Direct WebSocket

Agents can connect directly to ws://127.0.0.1:8766 and send JSON:

{"action": "navigate", "params": {"url": "https://example.com"}}

The CLI is a convenience wrapper - the WebSocket API is the core interface.

Performance

Benchmark results (v1.0.0 - January 2026):

CLI Performance (Rust vs Node.js)

The Rust CLI provides 88% faster command execution.

Command Timing Breakdown

Use --timing flag for detailed breakdown:

browser --timing navigate '{"url": "http://example.com"}'
# Returns: {"_timing": {"total_ms": 156, "connect_ms": 0, "roundtrip_ms": 155}, ...}

E2E Agent Benchmark Results (Claude Code + Opus 4.5)

Tested with Claude Code (claude-opus-4-5-20251101)

Timing breakdown:

• Total Time = LLM thinking + command execution (dominated by LLM API latency)
• Cmd Execution = actual browser commands only (~120ms/command average)

Note: Parallel E2E tests require isolated sessions (tabId) to avoid conflicts.

See benchmarks/README.md for the full benchmark suite and setup instructions.

Profiling

Use the --timing flag for latency breakdown:

browser --timing ping
# {"pong": true, "_timing": {"total_ms": 5, "connect_ms": 0, "roundtrip_ms": 5}}

See docs/setup.md, docs/api.md, and docs/performance.md for full details.

Binary Sizes

No Node.js runtime required.