Agent bridge

The agent bridge is the Extension.js channel between a running extension and whoever is watching it: a terminal, a script, or an AI agent. Reach for it when you want to read every extension context from outside the browser, or act on the extension without clicking through it yourself.

Quick start

npx extension@latest dev --allow-control

When extension dev runs, the framework loads a companion beside your extension and opens the channel on 127.0.0.1. Observation is always on, and --allow-control lets this session act as well.

A dev session with control on, then logs and storage read the running extension from a second terminal.

How it works

The companion lives only in the dev build. It connects every extension context (service worker, content scripts, popup, options, sidebar, devtools and the override pages) to the dev server, so one client sees them all in order.

Reading is free. Anything that changes state is opt-in per session: --allow-control unlocks storage, reload and open, and --allow-eval unlocks eval, implies control, and writes a 0600 session token. A refusal names the exact flag to restart with.

Everything stays on your machine. The channel binds to 127.0.0.1, needs no account, and sends nothing off the machine. The data plane, the addressing model and the limits are documented in the framework's Debugging section.

The MCP server reaches the same channel from an agent, so the agent and the CLI see the same thing. The platform stores none of it.

Reference

MCP tool	Transport
extension_logs, extension_storage, extension_reload, extension_open, extension_dom_snapshot	The bridge, as any other client
extension_eval	The bridge where the extension's content security policy allows it; the browser's debugger protocol where it does not
extension_inspect	The browser's debugger protocol on Chromium; the bridge on Firefox

When it fails

• An act command refuses and names a flag: the session was started without it. Restart extension dev with --allow-control, or --allow-eval for eval.
• extension_eval answers eval-disabled: no route of that tool runs without the session token. Start the session with allowEval: true from the agent, or --allow-eval from the terminal.

Next

• Debugging for the full story
• Agent logs and Inspect and act
• MCP server wires the bridge into an agent