doctor

STEP 1: State File Check

Check if .gsd/state.json exists:

• If exists: parse it as JSON
  • Valid JSON: record PASS with project name and workflow_mode
  • Invalid JSON (parse error): record FAIL with error details
• If not exists: record INFO "No active project (state.json not found)"

STEP 2: MCP Server Health

Call the health MCP tool:

• If returns status: "ok": record PASS with server version
• If returns error or unreachable: record FAIL with error message
• Note: if MCP server is not available at all (tool not found), record FAIL "MCP server not registered". Fix by install mode (STEP 3 says which): plugin — update or re-enable the gsd plugin; npx/manual — run npx gsd-lite install, which registers the server with Claude Code at user scope (claude mcp add -s user gsd …, needs claude on PATH) and prints the command to run by hand when it cannot. claude mcp list shows gsd once registered. Releases before 0.19.0 wrote the server only into settings.json, which Claude Code does not read MCP servers from, so an npx install from then has no gsd tools until it is reinstalled.

STEP 3: Hooks Registration

Check if GSD hooks are registered in Claude settings:

• Read ~/.claude/settings.json (or ~/.claude/settings.local.json)
• StatusLine check (registered if ANY path matches):
  1. Direct: statusLine.command contains gsd-statusline
  2. Composite cache registry: ~/.cache/code-graph/statusline-registry.json — any entry whose command contains gsd-statusline
  3. Composite backup mirror: ~/.claude/statusline-providers.json — same match rule (durable mirror written by code-graph's chain CLI)
  • Any path present: StatusLine = registered
• Determine the install mode first — hooks are registered in a different place for each, and checking only one reports a healthy install as broken:
  • Plugin: ~/.claude/plugins/installed_plugins.json lists gsd@gsd with a record that applies to this project (no scope, user or managed scope, or project / local scope whose projectPath is this project; a record for another project serves that project only), and enabledPlugins["gsd@gsd"] is not false in ~/.claude/settings.json or the project's .claude/settings.json / settings.local.json. Claude Code loads the three hooks from hooks/hooks.json in the plugin cache; nothing appears in settings.json and nothing is copied to ~/.claude/hooks/.
  • npx / manual: the three hooks are registered in settings.hooks and the five scripts sit in ~/.claude/hooks/.
  • Both can be true at once, and that is supported. The ~/.claude/hooks copies stand down, so each hook fires once, only when the files show the plugin serving this directory: the first entry under gsd@gsd (without one, under the first gsd@… id) is unscoped, at user scope, or at project / local scope for this directory; enabledPlugins["gsd@gsd"] is true in ~/.claude/settings.json or the project's .claude/settings.json / settings.local.json, and no other of them says otherwise; and the plugin's hooks/hooks.json declares the hook. Otherwise both copies run and each hook fires twice: record INFO "hooks from both the plugin and the npx install run", not a failure. A plugin installed by policy (managed scope) is enabled by managed settings these files do not show, so beside one both copies run.
• Plugin mode — read hooks/hooks.json from the entry's installPath and check it declares SessionStart, PostToolUse and Stop:
  • All three declared: record PASS "hooks served by the plugin"
  • Partial or the file missing/unparseable: record FAIL naming what is absent, fix: update the plugin — in a session /plugin → Installed → gsd → Update now, or from a shell claude plugin update gsd@gsd — then restart Claude Code
• npx/manual mode — check the three hook arrays in settings.hooks:
  • PostToolUse entry referencing gsd-context-monitor
  • SessionStart entry referencing gsd-session-init
  • Stop entry referencing gsd-session-stop
  • All three present: record PASS
  • Partial: record WARN naming each missing hook, fix npx gsd-lite install
• Neither mode registers all three: record FAIL "No GSD hooks registered"
• StatusLine: PASS if registered by any path above. Absent on a plugin-only install is expected, not a failure — a plugin may not write the top-level statusLine key. Record INFO "StatusLine needs npx gsd-lite install".