wtf is mv3-doctor?

mv3-doctor is a command line tool that checks Chrome browser extensions for mistakes specific to Manifest V3, the newer format Chrome now requires extensions to use. The tool exists because Manifest V3 changed some long standing assumptions that a decade of extension tutorials, and the AI models trained on them, still repeat. A common resulting bug looks fine while you are testing it, then fails once real users load the extension, because the background service worker that was warm during your test is not warm for them. Ordinary linters cannot catch these problems because the same line of code can be a bug in one file and perfectly fine in another. For example, using setInterval inside a service worker is broken, but the same function in a content script is fine. mv3-doctor solves this by first reading the extension's manifest.json to understand what role each script plays, then only applying the relevant rules to each one, so it reports real problems rather than flooding you with false alarms. You run it with npx against your built extension folder, not your source code, since that build output is what Chrome actually loads. It can run in continuous integration pipelines, and it can output plain colored text for humans or machine readable JSON for editors and AI coding agents. The project also ships a written skill file meant to teach an AI coding agent the Manifest V3 rules up front, and instruct it to run the validator before claiming its work is finished, so an agent both learns the rules and checks its own work. The tool includes about a dozen built in rules covering the manifest file, service worker restrictions, and unsafe code loading patterns, each with its own severity level and a documentation page, and individual findings can be suppressed with a comment when needed. It requires Node 20 or newer and is released under the MIT license.