doctor
Scan your Claude Code config, score it 0-100, and auto-fix issues.
The core of the tool. Runs 7 analyzers against your .claude/ directory and CLAUDE.md. An 8th (Memory) is added automatically when agentic-memory is detected.
Low scores signal real problems: conventions ignored, credentials exposed, context lost mid-session, every session starting from scratch. Doctor finds these gaps before they waste your time.
claude-launchpad doctorFlags
| Flag | Description |
|---|---|
--fix | Auto-fix: hooks, CLAUDE.md sections, rules, .claudeignore, credentials |
--fix --dry-run | Preview what --fix would change without applying |
--watch | Re-runs every second when config files change |
--min-score <n> | Exit code 1 if below threshold (for CI) |
--json | Pure JSON, no banner |
-p, --path <dir> | Run on a different directory |
Analyzers
| Analyzer | What it catches |
|---|---|
| Instruction Budget | Past ~200 lines, Claude stops reliably following rules at the bottom of CLAUDE.md. Doctor warns before you hit that limit. |
| CLAUDE.md Quality | Missing sections mean Claude guesses your stack, conventions, and boundaries. Vague instructions ("write good code") waste budget with zero signal. Also checks for a stop-and-swarm section so Claude spins up parallel agents after 3 failed attempts instead of retrying the same approach. Detects duplicate ## Memory headings (can happen if /lp-enhance runs before memory install; --fix collapses them). |
| Settings | Missing hooks, deprecated settings, auto-memory conflicts. Without proper settings, Claude runs without guardrails. |
| Hooks | Missing SessionStart = Claude forgets where you left off. Missing PostCompact = Claude loses context mid-session. Missing SessionEnd = memories never sync. Missing auto-format = inconsistent code style. Missing workflow-check.sh = BACKLOG/TASKS drift unmonitored. Detects hooks reading non-existent $TOOL_INPUT_* env vars (HIGH severity, silently inert) — these were shipped from v0.4.0 onward and never fired; --fix rewrites known shapes. |
| Rules | Missing BACKLOG.md, missing .claude/rules/workflow.md, missing .claude/rules/hooks.md, dead rule files, stale references. Without structure, deferred features get lost in conversation. |
| Permissions | Credential exposure (SSH keys, AWS creds), bypass mode enabled, filesystem sandbox enabled (blocks memory MCP and cross-project tooling). Security gaps that let Claude access what it shouldn't — or our own config choices that actively break it. |
| MCP Servers | Invalid transport configs, missing commands/URLs, MCP servers not in allowedMcpServers whitelist. allowedMcpServers is a security setting that restricts which MCP servers Claude can use -- without it, any server added to .mcp.json or settings is auto-trusted. --fix populates it from your configured servers. |
| Memory (optional) | MCP server config, hooks, autoMemory conflicts, CLAUDE.md guidance, tool permissions. Also cross-checks allowedMcpServers — if the allowlist is set without agentic-memory, the MCP server can't register and memory silently breaks. HIGH severity; --fix adds it back. Only runs when agentic-memory is detected. |
What --fix applies
Use --fix --dry-run to preview changes before applying. This is recommended for projects with existing configurations.
After --fix, use /lp-enhance inside Claude Code to restructure your CLAUDE.md. The fixer appends sections mechanically - the skill rewrites them into clean, project-specific content.
LP-STUB markers. --fix wraps injected sections in <!-- LP-STUB: ai-recommended --> markers. A stub-wrapped section still flags as missing. The marker tells doctor the content is scaffolding, not real. Replace the boilerplate (or delete the markers) to clear the flag. Running /lp-enhance does both in one pass.
When to re-run
Doctor isn't a one-time setup tool. It's a health check. Re-run it when:
- You add or remove dependencies
- You change frameworks or build tools
- You modify hooks, permissions, or settings manually
- Your score drops after an
enhanceor manual CLAUDE.md edit - Before a release, to catch config drift
Use --watch during active config editing to see your score update in real-time.