doctor

permitcrab:doctor

Read-only health check for permitcrab. Reports issues; does not fix them. To repair, invoke permitcrab:install or permitcrab:setup as the report suggests.

Checks

1. Node runtime present

Run node --version and verify it exits zero and reports v18 or newer. If node is missing or older than 18, report it and flag the install as broken; permitcrab's runtime entrypoints will fail to load.

2. Scripts present at ~/.permitcrab/

Verify each of the following exists, is a regular file, and is executable:

• ~/.permitcrab/resolve-permissions.js
• ~/.permitcrab/auto-deny-dangerous.js
• ~/.permitcrab/permission-notification.js
• ~/.permitcrab/VERSION

Verify the shared modules are present (regular files, executable bit not required since they are required as modules):

• ~/.permitcrab/lib/js-yaml.js
• ~/.permitcrab/lib/permissions.js
• ~/.permitcrab/lib/io.js

Missing or non-executable: report and suggest permitcrab:install.

3. Version match

Read ~/.permitcrab/VERSION and ${CLAUDE_PLUGIN_ROOT}/VERSION. If they differ, report version drift and suggest permitcrab:install. permitcrab's own SessionStart hook auto-repairs this on the next session start, but doctor should still surface it so the user knows.

4. Hook wiring in this plugin's hooks.json

Verify ${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json contains:

• A SessionStart hook pointing to ensure-installed.sh
• A PreToolUse:Bash hook pointing to auto-deny-dangerous.js
• A PermissionRequest:Bash|Read|Write|Edit hook pointing to ~/.permitcrab/resolve-permissions.js
• A Notification:permission_prompt hook pointing to ~/.permitcrab/permission-notification.js

Any missing or pointing elsewhere: report and explain how to fix (usually a re-clone or marketplace re-install).

5. Other plugins reference the right path

Use Grep (with output_mode: files_with_matches) to find resolve-permissions references in any hooks.json or SKILL.md outside permitcrab itself. For each hit, only Read the matching line range, not the whole file. The old per-plugin pattern uses ${CLAUDE_PLUGIN_ROOT}/scripts/resolve-permissions.*; those plugins should reference $HOME/.permitcrab/resolve-permissions.js instead, OR remove their local hook entirely and rely on permitcrab's global hook.

Report each instance found, with the file path. If more than 20 hits, summarize counts and list the first 20 only.

6. SKILL.md sanity

Use Grep to find SKILL.md files containing a permissions: block (pattern ^permissions:, output_mode: files_with_matches). For each hit:

• Read only the frontmatter section to check whether the block parses and whether matching tool usage is plausible.
• Flag files with a malformed block or with a permissions: block that declares operations none of the skill's allowed-tools cover.

This is a lightweight version of permitcrab:audit. Doctor reports the existence of problems; audit explains them. Do not walk the workspace exhaustively if the user is in a large monorepo - cap the report at 20 findings and suggest invoking permitcrab:audit for a deeper pass.

Output

Group findings by check. For each:

• Pass: a single line confirming.
• Warn: a paragraph describing the issue and the suggested remedy.
• Fail: same, plus a flag that this blocks permitcrab from working as designed.

End with a one-line overall verdict: healthy, degraded (warnings only), or broken (any failures).

What doctor does NOT do

• Fix anything. Doctor is read-only by design.
• Evaluate whether individual patterns are well-scoped. That's permitcrab:audit.
• Confirm Claude Code is actually loading permitcrab. If the plugin isn't installed, doctor won't run.