Skip to main content
Use doctor to find out why a dev session (or an automation verb talking to it) is not working. doctor walks the control-channel legs of a dev session in dependency order — from the on-disk readiness contract all the way to a live probe of the in-extension executor — and names the first failing leg with a concrete fix, instead of the dead-end error each command gives on its own.

​
When to use doctor

  • extension logs or an act verb can’t connect and you want to know which leg is broken.
  • An agent or script drives a session via ready.json and needs a machine-readable health check.
  • A dev session looks alive but the extension stopped responding.

​
Usage

If you omit the path, Extension.js diagnoses the session for the current working folder.

​
Arguments and flags

​
What it checks

Checks run in dependency order. When a leg fails, later checks that depend on it are marked skip and name the check that blocked them — a skip is not a pass. The pretty output prints one line per check plus the first failing check’s remediation. The exit code is 0 when nothing failed and 1 when any check failed, so CI and scripts can gate on it directly.

​
Machine-readable output

--output json prints the check results as a JSON array, one object per check:
status is pass, fail, or skip; remediation is present on failures that have a known fix.

​
Typical flow

  1. Start a session: extension dev --browser=chromium --allow-control (add --allow-eval for the eval verb).
  2. When a follow-up command can’t reach it, run extension doctor from the same project root.
  3. Apply the remediation printed for the first failing check, then re-run doctor to confirm.

​
Next steps

  • Read the readiness contract doctor starts from in dev.
  • Stream extension logs from a healthy session with Debugging.
  • Review shared flags in Global flags.