comet doctor

comet doctor tells you why Comet is currently failing. It checks the installation environment, CLI and dependencies, project directories, Skill/Rule/Hook assets, Runtime, CodeGraph, and the current change status. Think of it as an environment and workspace health check: comet status tells you workflow position, while comet doctor tells you fault location. The default check is read-only and will not repair or rewrite items due to diagnosis. Supported repair actions will only be executed when --repair is explicitly used. CodeGraph is reported in four independent dimensions: CLI installation status, project index status, MCP registration status, and per-Agent effective capability. An up-to-date index only means data is synced; it does not guarantee that an Agent can use CodeGraph. For precise diagnosis, inspect the codegraph object in JSON output.

Basic usage

comet doctor
comet doctor --scope project
comet doctor --json

Options	Explanation
`--json`	Output structured diagnosis.
`--scope <scope>`	Diagnose `auto`, `project` or `global`. The default is `auto`.
`--repair`	Fix the Hook, Rule and current change selection state managed by Comet.
`--strategy <strategy>`	Restore the Classic root directory migration with values of `continue` or `rollback`; It must be used together with `--repair`.
`--yes`	Confirm project repairs that require user consent, such as CodeGraph indexes; It must be used together with `--repair`.

First, let’s look at the text output

For example, when the project-level Skill has not been installed, the Classic root directory is missing, and the CodeGraph still has content to be synchronized, comet doctor --scope project will print:

Comet Doctor (scope: project)

  ✓ Environment: node v22.20.0; platform win32/x64; project D:\Project\Comet; global C:\Users\BENYM
  ✓ Comet CLI: installed (0.4.0-beta.20)
  ✓ openspec CLI: installed (1.7.0)
  ✓ Superpowers: detected (Claude Code project, Codex project, Antigravity project, Antigravity 2.0 project; version not recorded by skills installer)
  ✗ Classic artifact layout: docs: configured docs/openspec/ missing; alternate openspec/ missing — run: comet classic root show, then restore the configured root or use comet classic root move
  ✓ Classic platform tool assets: no OpenSpec platform tool assets under docs/
  ✗ Classic OpenSpec root: Configured Classic OpenSpec root is missing: docs/openspec (alternate openspec is missing)
  ⚠ working directories: partial (missing: docs/openspec/changes, docs/openspec/changes/archive, docs/openspec/specs)
  ⚠ Comet skills: not installed in project scope — run: comet init --scope project
  ✓ scripts present: OK (12 scripts)
  ✓ CodeGraph CLI: CodeGraph CLI is installed
  ⚠ CodeGraph project index: CodeGraph index has 1 pending change(s) — run: codegraph sync
  ⚠ CodeGraph MCP registration: no supported Agent configuration detected
  ✓ current selection: no active Comet change

The version, path and quantity will vary with your environment, but the output structure remains the same. Understand by symbol:

✓: This check has passed and no further processing is required.
⚠: Detected warnings or missing optional components. In most cases you can continue, but follow the suggested action as soon as practical.
✗: This check failed. Prioritize processing this line and the commands following run:.

In this example, what really needs to be prioritized is the Classic root directory: the configuration points to docs/openspec/, but the directory does not exist. First, run comet classic root show to view the actual configuration, and then restore the directory or use comet classic root move. current selection: no active Comet Change is not an error. It only indicates that Comet Change is not selected at present.

Which issues should be checked?

Each line in the output corresponds to a type of check:

Output item	Inspection function
`Environment`	What are the current Node, platform, project path and global directory?
`Comet CLI` / `openspec CLI`	Whether the CLI is installed and the current version.
`Superpowers`	Is the external Superpowers available?
`Classic artifact layout` / `Classic OpenSpec root`	Whether the root directory of the Classic configuration exists and is readable.
`working directories`	Are the working directories such as `changes`, archive directory and `specs` complete?
`Comet skills` / `scripts present`	Are the Skill and Runtime scripts of the current scope complete?
`CodeGraph CLI`	Has the CodeGraph CLI been installed?
`CodeGraph project index`	Whether the current project index is up to date, incomplete, outdated or uninitialized.
`CodeGraph MCP registration`	Whether the detected Agent has registered a valid CodeGraph MCP.
`CodeGraph effective for <Agent>`	Whether the Agent simultaneously possesses the CLI, the latest index and a valid MCP registration.
`current selection`	Is there a Comet Change to which the current write belongs?

Select the inspection range

--scope auto: Default value. First, check the current project; If the project is not fully installed, check the available global installations again.
--scope project: Only checks the current project, suitable for confirming whether the local initialization of the project has been completed.
--scope global: Only checks global installations, suitable for troubleshooting global skills, rules, hooks or runtimes.

If the global Comet installation is complete but the current project does not have a project-level Skill copy, --scope auto will report that the global installation is available and consider the project-level copy as an option. Run only when the project requires its own Comet configuration and a copy of the Skill:

comet init --scope project

How to read JSON output

When automated processing is required, use:

comet doctor --json

The top-level output will first tell you the overall result:

{
  "scope": "project",
  "status": "failed",
  "healthy": false,
  "repaired": [],
  "results": [
    {
      "check": "Comet CLI",
      "status": "pass",
      "message": "installed (0.4.0-beta.19)"
    },
    {
      "check": "Classic OpenSpec root",
      "status": "fail",
      "message": "Configured Classic OpenSpec root is missing: docs/openspec"
    }
  ]
}

healthy: false indicates that there is at least one fail. The specific handling method is in results[].message. Both status: passed and healthy: true indicate that there are no failed items in this diagnosis. The runtime and codegraph fields will also provide the Runtime source and detailed status of the CodeGraph. The codegraph object includes cliStatus, indexStatus, mcpStatus, agents and effectiveForAgent. The Agent will only be marked as effective when the CLI is installed, the project index is up to date, and the corresponding MCP configuration points to the CodeGraph service.

When should `--repair` be used

First, run comet doctor without --repair to confirm the problem and suggest the action. Run only when the output clearly points to the fix, or when you have confirmed that you want to fix the Hook, Rule, selection, or migration site managed by Comet:

comet doctor --repair

--repair will perform a write operation. When the migration of the Classic root directory is interrupted, select continue or rollback according to the scene. For project repairs that require your confirmation, such as CodeGraph, add --yes. If you only want to recheck, please omit --repair.

Install and health checks

Skills, evals, and publishing

Core scripts

Basic usage

First, let’s look at the text output

Which issues should be checked?

Select the inspection range

How to read JSON output

When should `--repair` be used

Troubleshooting sequence

​Basic usage

​First, let’s look at the text output

​Which issues should be checked?

​Select the inspection range

​How to read JSON output

​When should --repair be used

​Troubleshooting sequence

Basic usage

First, let’s look at the text output

Which issues should be checked?

Select the inspection range

How to read JSON output

When should `--repair` be used

Troubleshooting sequence