| name | harness-doctor |
| description | Diagnose and fix your Claude Code harness. Scans CLAUDE.md, settings.json, hooks health, and stack consistency. Produces scored report. Run /shipwithai-harness:doctor |
| version | 1.0.0 |
| license | MIT |
Harness Doctor
Diagnostic tool for existing Claude Code harness setups. Detects missing files, misconfigured permissions, broken hook wiring, and stack mismatches. Produces a scored health report with actionable fixes.
When to Use
- After running
harness-setup — final validation
- Harness seems to not be working (Claude ignoring CLAUDE.md or hooks)
- After moving a project or cloning a repo — check hooks are executable
- Periodic health check
Step 1: Detect Stack (SILENT)
Run same detection as harness-setup Step 0. Same token auto-fill logic.
Show scan summary before proceeding:
🔍 Harness Doctor — Scanning project...
Stack: Next.js (Next.js 14.2.18)
Detected: CLAUDE.md ✓ settings.json ✓ hooks/ ✓
Step 2: Run Diagnostic Checks
Run all 4 categories unless $ARGUMENTS specifies one. Read references/doctor-checks.md for full check details per category.
| Category | Key checks |
|---|
| Memory | CLAUDE.md exists, < 200 lines, no unfilled {{TOKEN}}, Last verified < 90 days old |
| Permission | .claude/settings.json exists, valid JSON, has deny block, curl/npx not hard-denied |
| Hooks | validate-command.py + protect-files.py exist, executable, wired in settings.json |
| Stack | detected stack matches CLAUDE.md stack line, commands exist in project |
Step 3: Health Report
╔══════════════════════════════════════════════════╗
║ 🛡️ Harness Doctor — Health Report ║
╠══════════════════════════════════════════════════╣
║ Stack: Next.js ║
║ Score: 11/12 checks passed ║
╚══════════════════════════════════════════════════╝
Category Status Issues
──────────────────────────────────
1. Memory ✅ 0
2. Permission ⚠️ 1 warning
3. Hooks ❌ 1 critical
4. Stack ✅ 0
──── CRITICAL ────────────────────
❌ .claude/hooks/validate-command.py not executable
Fix: chmod +x .claude/hooks/validate-command.py
──── WARNINGS ────────────────────
⚠️ CLAUDE.md Last verified: 2026-01-15 (114 days ago)
Recommendation: Review and update to reflect current project state
Step 4: Offer to Fix
Found {N} issues ({X} critical, {Y} warnings).
A) Fix all — apply all safe fixes automatically
B) Fix critical only
C) Show me the fixes first
D) Skip
Safe auto-fixes (no user confirmation needed):
chmod +x on hooks- JSON formatting fixes in settings.json
Always ask before:
- Modifying CLAUDE.md content
- Changing settings.json deny/allow rules
