doctor — Claude Code Config Linter
Lint your Claude Code setup: score CLAUDE.md, hooks, permissions, and MCP config 0-100, then auto-fix the gaps offline and free. The CLAUDE.md linter with 9 analyzers.
The core of the tool. Runs 7 core analyzers against your .claude/ directory and CLAUDE.md, plus a Workflow analyzer when BACKLOG.md exists and a Memory analyzer 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. SessionStart matcher missing compact = context lost mid-session (PostCompact exists but is side-effect-only — its stdout is never injected; doctor flags dead PostCompact injection hooks HIGH and --fix migrates them). Missing SessionEnd = memories never sync. Missing auto-format = inconsistent style. Missing workflow-check.sh = BACKLOG/TASKS drift unmonitored. Missing jq on PATH = every generated hook (including the blocking guards) silently no-ops (MEDIUM). Detects hooks reading non-existent $TOOL_INPUT_* env vars (HIGH, silently inert); --fix rewrites known shapes. |
| Rules | Missing BACKLOG.md, missing .claude/rules/workflow.md, missing .claude/rules/hooks.md, missing .claude/rules/verification.md (nothing stops premature "done" claims without evidence), dead rule files, stale references. Without structure, deferred features get lost in conversation. |
| Permissions | Credential exposure (SSH keys, AWS creds), bypass mode enabled, sandbox missing a ~/.agentic-memory write grant when memory is installed (doctor scopes the sandbox — it never disables it). Security gaps that let Claude access what it shouldn't. |
| 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. |
| Workflow (when BACKLOG.md exists) | Batch audits the hooks can't do per-edit: WP entries missing mandatory template fields, P0 items older than 14 days (P0 means next sprint), a changelog silent for 30+ days while WPs sit in the backlog. |
| 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.
Next
init — Scaffold a Claude Code Setup
Scaffold a complete Claude Code setup in seconds: CLAUDE.md, security hooks, permissions, verification rules, backlog workflow, and a code-reviewer agent — auto-detected for your stack.
eval — Test Your Claude Code Config
Run Claude Code against 17 test scenarios in isolated sandboxes and prove your CLAUDE.md, hooks, and permissions actually change behavior. File, transcript, and AI-judge checks.