# Firefox Agent Bridge
Bridge a WebSocket-connected AI agent to your real, logged-in browser via a WebExtension and a
native host. One extension source tree ships to **Firefox**, **Chrome/Chromium-family browsers**
(Chrome, Edge, Brave, Chromium) and **Safari**.
| Browser | Package | Transport |
|---------|---------|-----------|
| Firefox | MV2 `.xpi` | native messaging |
| Chrome, Edge, Brave, Chromium | MV3 (`dist/chrome`, stable ID `ijifgeepmnbalajhfjnpbnobfobflfkk`) | native messaging |
| Safari 17+ (macOS) | MV3 wrapped in an app by `scripts/package-safari.sh` | local WebSocket relay (`host --relay`, port 8767) |
Build all packages with `python3 scripts/build-extensions.py` (outputs to `dist/`).
Chromium notes: `evaluate` runs in the page's main world. On pages whose CSP forbids eval it
uses the `userScripts` world when "Allow user scripts" is enabled for the extension, otherwise it
falls back to a short-lived `chrome.debugger` attach.
Safari cannot launch arbitrary native messaging hosts, so the host runs in relay mode and the
extension dials `ws://127.0.0.1:8767/extension`. Both host sockets reject connections that carry a
web page `Origin`, so websites cannot drive the browser.
## 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 Browser Extension
`jcode browser setup` detects your default browser and does all of this for you. Manual steps:
**Chrome / Edge / Brave / Chromium:** unzip `browser-agent-bridge-chrome-X.X.X.zip`, open
`chrome://extensions`, enable Developer mode, then "Load unpacked". Register the native host with
`allowed_origins: ["chrome-extension://ijifgeepmnbalajhfjnpbnobfobflfkk/"]` in the browser's
`NativeMessagingHosts` directory.
**Safari:** run `scripts/package-safari.sh` on a Mac with Xcode, open the built app once, and enable
the extension in Safari > Settings > Extensions. Start the host with `firefox-agent-bridge-host --relay`.
**Firefox:**
Download the signed extension from [GitHub Releases](https://github.com/1jehuang/firefox-agent-bridge/releases/latest):
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)
```bash
# 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
```bash
# 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:
```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)
| CLI | Per-Command | Improvement |
|-----|-------------|-------------|
| **Rust** (`browser`) | **12ms** | baseline |
| Node.js (`client.js`) | 105ms | 8.75x slower |
The Rust CLI provides **88% faster** command execution.
### Command Timing Breakdown
Use `--timing` flag for detailed breakdown:
```bash
browser --timing navigate '{"url": "http://example.com"}'
# Returns: {"_timing": {"total_ms": 156, "connect_ms": 0, "roundtrip_ms": 155}, ...}
```
| Action | Total (ms) | Connect (ms) | Roundtrip (ms) |
|--------|-----------|--------------|----------------|
| ping | 3-8 | 0 | 3-8 |
| navigate | 150-170 | 0 | 150-165 |
| getContent | 2-33 | 0 | 2-33 |
| type | 2-11 | 0 | 2-11 |
| click | 2-5 | 0 | 2-5 |
| fillForm | 3-10 | 0 | 3-10 |
### E2E Agent Benchmark Results (Claude Code + Opus 4.5)
| Task | Status | Commands | Total Time | Cmd Execution | Description |
|------|--------|----------|------------|---------------|-------------|
| table-scrape | PASS | 3 | ~15s | ~0.2s | Extract 8-row data table |
| oauth-flow | PASS | 8 | ~40s | ~1s | Complete mock Google OAuth |
| contact-form | PASS | 4 | ~20s | ~0.15s | Fill and submit form |
| login-flow | PASS | 12 | ~25s | ~1.5s | Login and extract secrets |
*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:
```bash
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
| Binary | Size | Purpose |
|--------|------|---------|
| `browser` | 1.2MB | CLI for sending commands |
| `firefox-agent-bridge-host` | 830KB | Native messaging host |
No Node.js runtime required.