extension_dom_snapshot
Take a shallow structured DOM snapshot of one chosen surface through the agent bridge (localhost only; the snapshot itself needs no CDP, but listTargets and tabUrl resolution ask the browser directly and need the session's debug port: CDP page targets on Chromium, RDP tab descriptors on Firefox): element counts, extension roots, open shadow roots, optional byte-capped HTML, and optional recent console lines.
Quick start
Snapshot the popup and tell me what it rendered
Asked what a surface rendered, the agent runs the extension and snapshots the page.
How the agent uses it
This is the SURFACE PICKER: the only tool that reads an open extension surface by name (context: popup, options, sidebar, devtools) or an override page, the only one that takes a numeric chrome.tabs id, and the only one that enumerates what is open (listTargets for CDP targetIds and RDP tab actors, listTabs for numeric tab ids). An ambiguous tabUrl returns the candidates instead of guessing. It does not pierce closed shadow roots, run selector probes, or navigate: use extension_inspect for those, and for a deep read of an already-open web page. Rides the dev session's control channel, on unless extension_dev was called with allowControl:false.
Page text in the answer
Part of this tool's answer is text a web page or the extension wrote. The server fences it between <untrusted-data-ID> and </untrusted-data-ID> with a fresh random ID per call, named in untrusted.boundary. A fence is a signal to the model, not a gate: pair it with --no-ship when the agent reads pages you do not trust. See Server flags and telemetry.
Reference
| Group | local, on by default |
| Tier | See |
| Needs | a dev session, which carries control unless started with allowControl: false |
| Read only | yes |
| Destructive | no |
| Idempotent | yes |
| Reaches the open web | no |
Inputs
| Input | Type | Required | Default | What it does |
|---|---|---|---|---|
projectPath | string | yes | Extension project root (needs a live dev session) | |
tab | number | no | Numeric chrome.tabs id, only to disambiguate when several tabs match. With neither tab nor url, content/page target the active tab. | |
url | string | no | content/page: pick the tab by url (match pattern, then substring). Preferred over tab. | |
tabUrl | string | no | Target the tab whose URL contains this substring (case-insensitive; titles checked only when no url matches). Resolved against the live browser first: exactly one match proceeds, zero or several return the candidates instead of a guess. Alternative to url. | |
listTargets | boolean | no | false | Enumerate live page targets and return, ignoring the other args. The discovery path for tabUrl. Chromium: {targetId,url,title,type}. Firefox: RDP tab descriptors {actor,url,title,type}. Neither id is a numeric chrome.tabs id; for those use listTabs. |
listTabs | boolean | no | false | Enumerate open tabs as {tabId,url,title} and return, ignoring the other args. Use when you need a numeric tab id. |
context | "content" | "page" | "popup" | "options" | "sidebar" | "devtools" | "newtab" | "history" | "bookmarks" | no | "content" | content/page targets url, else the active tab; the rest must already be OPEN |
include | array of "summary" | "html" | no | ["summary"] | What to include; html is byte-capped |
maxBytes | number | no | 262144 | |
withConsole | number | boolean | no | Also include recent console lines. A number is how many; true means 50. | |
browser | string | no | Session browser; defaults to this project's live session | |
timeout | number | no | Command timeout in ms. When omitted, the default depends on the route: 30000 through the dev session's control channel, 10000 over the Firefox debugger protocol, and 15000 per command over the Chromium debug port. |
When it fails
- The call is refused because no session is live. Start one with
extension_devorextension_startand call again. - The control channel is off. The session was started with
allowControl: false. Start it again without that flag.
Next
- MCP server: install, the two groups and the session gates
- Install in your client
extension_analyze: Analyze a BUILT extension on disk: file sizes, declared entry points, permissions, bundle composition, and store-readiness checks.extension_doctor: Diagnose a dev session end to end: ready contract, dev-server process, control-port agreement, control channel, eval token, executor, browser liveness.extension_inspect: Inspect a running extension deeply over the browser's debugger protocol: full HTML (open shadow roots of #extension-root and [data-extension-root] hosts inlined; other shadow ro...extension_list_extensions: List the extensions in the running dev browser: id, name, version, and, on Chromium, live contexts.extension_logs: Read or stream logs from every context of a running dev session (service worker, content scripts, popup, options, sidebar, devtools, pages) in one ordered timeline.extension_manifest_validate: Validate a manifest.json across browsers.extension_theme_verify: Verify a Chrome theme manifest before it ships.