Inspect and act

Inspect and act are the Extension.js commands that read a running extension and change it from outside the browser: inspect reads the live, post-injection DOM of any surface, and eval, storage, reload and open run inside the extension's own context. Reach for them when "it should work" needs proof, on Chrome and Firefox, with no account.

Quick start

npx extension@latest dev --allow-control
npx extension@latest inspect --context content --url example.com

The first command starts a session that may act. The second reads the DOM your content script produced on the matching tab. Add --allow-eval to the first line to unlock eval as well.

inspect reads the page the content script runs on, then open raises the options page.

How it works

Every command goes through the agent bridge, the in-browser companion the dev session loads, not the Chrome DevTools Protocol. That is why the same loop reaches your own surfaces on both Chrome and Firefox.

inspect addresses content, page, or any open surface: popup, options, sidebar, devtools, newtab, history and bookmarks. --url picks the tab by glob or substring, and --tab picks one by id.

Acting is gated per session, not per verb. storage, reload, inspect, navigate and open need a session started with --allow-control. eval needs --allow-eval, which implies control and writes a 0600 session token outside dist/. A refusal names the exact flag to restart with.

The MCP server reaches the same machinery from an agent under the same gates, which extension_dev names allowControl and allowEval. Nothing the agent reads or touches here leaves your machine. The addressing model, the safety gates and every flag live in the framework's Debugging section.

Reference

CLI command	MCP tool	Needs
extension inspect	extension_inspect	CLI: --allow-control. MCP: the browser's debugger protocol on Chromium, the bridge on Firefox
none	extension_dom_snapshot	allowControl
extension storage	extension_storage	--allow-control / allowControl
extension reload	extension_reload	--allow-control / allowControl
extension open	extension_open	--allow-control / allowControl
extension navigate	extension_open with url	--allow-control / allowControl
extension eval	extension_eval	--allow-eval / allowEval, which implies control

When it fails

• A command refuses and names --allow-control or --allow-eval: the running session lacks that unlock. Restart extension dev with the named flag, then retry.
• extension_eval answers eval-disabled: the session was started without allowEval: true, and no route of the tool runs without that token. Call extension_dev again with allowEval: true and replace: true.
• inspect finds no document for a surface: the surface is not open. Open it first with extension open options (or extension_open), then inspect it.
• extension open popup refuses on Chromium: Chromium opens a popup only in response to a user gesture. Click the toolbar button, or replay the click handler with extension open action on an action without a popup.

Next

• Debugging for the full story
• Agent logs streams what act operations produce
• MCP server wires these into an agent