plan-doctor — Claude Code command: what it does, how to install
The plan-doctor command for Claude Code checks planning-with-files plan lookup, injection, and attestation. Run it when hooks go silent or on a new machine.
MIT ★ 28,179 updated 2026-10-24
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-filesWhat plan-doctor does
/plan-doctor runs plan-doctor.sh from the project root and prints PASS, WARN and FAIL lines. It covers the parts of planning-with-files that fail without a sound: finding the active plan, hook injection, the path shape the canonicalizer sees, attestation state, install surfaces and how long each hook fire takes.
These mechanisms exit 0 and say nothing when something is wrong, so a broken install looks the same as a project with no plan yet. The doctor separates the two. The agent relays the report as printed. On a FAIL it explains the fix. For the resolver, look at .planning/.active_plan and the plan directory names. For injection when a plan does resolve, check PLANNING_DISABLED and upgrade past v3.6.0, which fixes a realpath problem with Windows-native coreutils. A tamper WARN clears when you re-approve with /plan-attest, provided you made the plan edit yourself.
It only diagnoses and never applies fixes. It needs the Bash tool, and on Windows without Git Bash on PATH the agent finds sh.exe next to git.exe. The model will not run it on its own, because the command sets disable-model-invocation: true. You type it.
What it helps with
- find out why the planning-with-files hooks are silent
- verify a plugin install on a new machine
- check whether the active plan resolves from
.planning/.active_plan - catch hook injection failing while the plan is found
- see how long each hook fire takes
Example prompts for the agent
- Run
/plan-doctor, the planning-with-files hooks have gone quiet - I installed the plugin on a new laptop, check it with
/plan-doctor - Run
/plan-doctorand show me the PASS, WARN and FAIL lines unchanged
How to install plan-doctor
1Plugin marketplace
/plugin marketplace add OthmanAdi/planning-with-files/plugin install planning-with-files@planning-with-files2Manually: put the files in place
.claude/commands/plan-doctor.mdCall it with /plan-doctor. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/plan-doctor.mdCall it with /prompts:plan-doctor. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/plan-doctor.prompt.mdManually: put the files in place
.gemini/commands/plan-doctor.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about plan-doctor
How do I install plan-doctor in Claude Code?
Run /plugin marketplace add OthmanAdi/planning-with-files, then /plugin install planning-with-files@planning-with-files. To install the command by hand, put the file at .claude/commands/plan-doctor.md.
What does plan-doctor do?
It runs plan-doctor.sh in the current project and reports PASS, WARN or FAIL for plan resolution, hook injection, canonicalizer path shape, attestation state, install surfaces and hook latency. It exists because those mechanisms stay silent when they break.
Does plan-doctor work in Codex, and does it fix problems itself?
Codex is a supported platform, and its command file goes to ~/.codex/prompts/plan-doctor.md. The command fixes nothing. It diagnoses and tells you what to do after a FAIL.
Source text
plan-doctor.md · MIT
---
description: "Self-check for the planning-with-files mechanisms that fail silently: plan resolution, hook injection, canonicalizer path shape, attestation state, install surfaces, and per-fire hook latency. Run it whenever hooks seem quiet or after installing on a new machine. Available since v3.6.0."
disable-model-invocation: true
allowed-tools: "Bash"
---
Run the planning-with-files self-check against the current project directory.
Steps:
1. Run the doctor script from the project root:
- Linux/macOS/Git Bash: `sh ${CLAUDE_PLUGIN_ROOT}/scripts/plan-doctor.sh`
- Windows without Git Bash on PATH: locate Git Bash via `git.exe` (its `usr\bin\sh.exe` sibling) and run the same script with it.
2. Report the PASS/WARN/FAIL lines to the user verbatim — they are designed to be read as-is.
3. If any line reports FAIL, explain the matching remediation:
- resolver FAIL → inspect `.planning/.active_plan` content and plan dir names.
- injection FAIL with a resolving plan → the hooks are silently dark; upgrading past v3.6.0 fixes the Windows-native-coreutils realpath cause. Also check `PLANNING_DISABLED`.
- tamper WARN → re-approve with `/plan-attest` if the plan edit was intentional.
4. Do not attempt automatic fixes; this command is diagnostic only.
Why this exists: the mechanisms this skill relies on (hook injection, plan resolution) exit 0 and stay silent by design when something is off, so a broken install looks identical to "no plan yet". The doctor makes the difference visible in one pass.
© OthmanAdi · MIT · OthmanAdi/planning-with-files