| name | doctor |
| description | Diagnostic suite for Oh-My-Link workspace health -- checks runtime state, locks, tasks, hooks, build, and path resolution |
Run a full health check on the Oh-My-Link installation and active session.
Reports PASS/WARN/FAIL per check and offers auto-fix for common issues.
Useful after errors, unexpected stops, or before starting a complex workflow.
<Use_When>
- User says
doctor oml or doctor oh-my-link
- Something seems broken or stuck (especially "hook error" messages)
- After an interrupted session to detect orphaned state
- Routine health verification before starting a new feature
</Use_When>
Step 1 -- Plugin root and build check
Determine the plugin root (from ~/.oh-my-link/setup.json -> pluginRoot field,
or from current directory if .claude-plugin/plugin.json exists).
Check that {pluginRoot}/dist/hooks/keyword-detector.js exists.
Compare mtimes: any src/**/*.ts newer than the newest dist/**/*.js?
FAIL if dist/ does not exist.
WARN if build is stale (src newer than dist). Suggest: npm run build.
PASS if dist/ is up-to-date.
Step 2 -- Hook path validation
Read .claude/settings.json. For each of the 10 hook events:
- Check the hook entry exists
- Check the hook command path resolves to an actual file on disk
- Check the path is absolute (not relative, not using
${CLAUDE_PLUGIN_ROOT})
Common failure modes:
${CLAUDE_PLUGIN_ROOT} in path -> "Variable not resolved. Run setup oml to fix."- Relative path (
dist/hooks/...) -> "Only works from plugin directory. Run setup oml to fix."
- Absolute path to non-existent file -> "Plugin may have been moved. Run
setup oml to fix."
- Missing hook entry -> "Hook not wired. Run
setup oml to fix."
PASS if all 10 hooks are wired with valid absolute paths.
WARN/FAIL otherwise with specific guidance per hook.
Step 3 -- Runtime directory check
Compute project hash and check that ~/.oh-my-link/projects/{hash}/ exists.
Check for: session.json, project-memory.json.
PASS if all exist, WARN if directory exists but files missing, FAIL if missing entirely.
Step 4 -- Artifact directory check
Verify in project root: .oh-my-link/ with 6 subdirectories
(plans, history, tasks, locks, context, skills).
Report count present vs expected (6). Offer mkdir -p for missing ones.
Step 5 -- Session state validity
Read session.json. Attempt JSON parse. Check required fields:
active, mode, current_phase, started_at.
FAIL if invalid JSON or missing required fields.
WARN if active: true but started_at > 24h ago (stale session).
Step 6 -- Orphaned lock files
Read all files in .oh-my-link/locks/. Check expires_at timestamps.
WARN if any expired locks exist. Offer to delete them.
Step 7 -- Orphaned tasks
Read all files in .oh-my-link/tasks/. For each in_progress task,
check if a corresponding subagent is still running.
WARN if tasks are in_progress with no active subagent. Offer to mark as failed.
Step 8 -- Dependency cycle check
Load all task files. Build dependency graph. Run DFS cycle detection.
FAIL if cycles detected. PASS if clean.
Step 9 -- Summary report
Check Status Detail
------------------------------------------------------
Plugin root + build PASS D:/Oh-My-Link, fresh
Hook paths (10/10) WARN 2 hooks use relative paths
Runtime dirs PASS
Artifact dirs (6/6) PASS
Session state PASS active, phase_5_execution
Orphaned locks PASS 0 expired
Orphaned tasks WARN 1 stale in_progress
Dependency cycles PASS
------------------------------------------------------
Overall: 6 PASS 2 WARN 0 FAIL
For each WARN/FAIL with an auto-fix available, prompt user before applying.
For hook path issues, recommend: setup oml (the setup wizard handles path repair).
<Tool_Usage>
- Bash: stat for mtime comparisons, node -e for JSON parse checks, file existence tests
- Read: session.json, task files, lock files, settings.json, setup.json
- Write: only when auto-fixing (delete expired locks, update task status)
- No Agent spawning -- doctor runs diagnostics in the current session
</Tool_Usage>
