Agent logs

Agent logs are the one ordered stream Extension.js writes while extension dev runs: every context of the extension, in sequence, in a local file. Reach for them when you need to know what the service worker, a content script and the popup did, in the order they did it, without opening four consoles.

Quick start

npx extension@latest logs

Run it beside a dev session to print the most recent lines, or add --follow to keep streaming. The file behind it is dist/extension-js/<browser>/logs.ndjson.

logs --follow in a second terminal streams the background, new tab and content script lines as the page loads.

How it works

The agent bridge merges every context into one timeline: background, content, page, popup, options, sidebar, devtools, newtab, history and bookmarks. The session appends each event to logs.ndjson under dist/extension-js/<browser>/.

A one-shot read needs no channel and no unlock. It is local, needs no account, and the file never leaves your machine. The line format and the flags live in the framework's Debugging section and the logs reference it links.

Rotation is not documented there yet. When the writer rotates the file, extension logs announces it on stderr and names the sibling the earlier events moved to.

The MCP server's extension_logs reads the same stream from an agent. It is bounded by default, so it does not flood the agent's context: a one-shot returns the most recent matching lines, and follow collects for a bounded window. There is no platform log retention, and logs are never uploaded.

Reference

extension logs flag	Effect
--follow	Keeps streaming instead of returning the most recent lines
--context <list>	Only these contexts, from the ten above
--since <seq|iso>	Only events after a sequence number or a timestamp
--url <glob|substring>	Only events from documents at a matching url
--tab <id>	Only events from one tab

extension_logs default	Value
Lines per one-shot read	200
follow window	4000 ms

When it fails

• extension logs finds no file: no dev session has written one for that browser. Start extension dev for that browser, then read again.
• extension_logs answers E_LOGS_MISSING on Safari: the extension is not enabled yet, or the project runs an engine older than 4.1.21. Turn it on in Safari > Settings > Extensions, then read again. See Run on Safari.
• The stream announces a rotation: the earlier events of this session live in the sibling file it names. Read that file for the lines before the rotation.

Next

• Debugging for the full story
• Inspect and act reads the DOM and calls into the extension
• MCP server wires the stream into an agent