doctor

review-gate — doctor

Diagnose whether the push gate can actually run on this machine, and report it plainly. Read only — never install, modify, or repair anything. Say what is wrong and what the user should run; let them decide.

This exists because of one hard constraint: a hook that fails to launch, times out, or dies abnormally is treated by Claude Code as non-blocking. If the gate cannot start, pushes are simply not reviewed, and nothing announces it. That failure is undetectable from inside the hook, so it has to be checkable on demand. That is this command.

What to check

Run these and collect the results. Prefer one Bash call per group; keep going if a command fails — a failure is a result.

1. Prerequisites

• claude --version — the reviewer shells out to this. Missing ⇒ the gate fails open by design (there is no gate without the tool).
• A working Python 3: try python3 -c "import sys; print(sys.version)", then python, then py. Ignore any interpreter whose path contains WindowsApps — those are Store alias stubs that resolve but cannot execute. Missing ⇒ the gate now fails closed (blocks pushes) as of 0.3.0.
• git --version.
• On Windows only: is Git Bash present? Check bash --version, and note the path — a bash.exe under System32 is WSL, not Git Bash. Also look for bin\bash.exe or usr\bin\bash.exe next to git.exe's install root, since Git for Windows' "command line only" option keeps bash off PATH while Claude Code can still use it.

2. Plugin wiring (the default adapter)

• Read ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json and report version.
• Read ${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json. Confirm there is a PreToolUse entry matching Bash (it carries if: "Bash(git *)", which is best-effort only — the adapters re-check the command themselves, so treat a missing or different if as cosmetic, not a fault), and report each entry's timeout.
• Confirm there is also a PostToolUse entry matching Bash. This is the adapter that puts non-blocking findings into the session's context after a push; without it, a warn verdict is recorded but never surfaced to the model. It deliberately has no if clause and a short timeout (30s) — it only reads a file. Flag a large timeout here as wrong, not as safe.
• List pending-* in the plugin data dir ($CLAUDE_PLUGIN_DATA, else ~/.claude/plugins/data/review-gate-local). These are reviews recorded but not yet reported — the mechanism that lets findings survive a push that failed. A handful is normal and they expire after an hour. Many, all stale, means delivery is not running: check the PostToolUse entry above.
• Check all four adapter scripts exist and are readable: ${CLAUDE_PLUGIN_ROOT}/scripts/gate-hook.sh, gate-hook.ps1, post-hook.sh, and post-hook.ps1.
• Confirm each hook timeout is greater than OCR_TIMEOUT (default 1800). If not, say so loudly: Claude Code kills the hook at its own deadline regardless, and a killed hook is non-blocking — i.e. a silent fail-open.