doctor — Coding-agent config linter
Lint Claude Code or Cursor Agent setup: score instructions, hooks, permissions, and MCP config 0-100, then auto-fix the gaps offline and free.
The core of the tool. For Claude Code it runs 7 core analyzers against .claude/ and CLAUDE.md, plus Workflow when BACKLOG.md exists and Memory when agentic-memory is detected. For Cursor Agent it scores AGENTS.md, .cursor/hooks.json, rules, ignore, and MCP separately. Scores are never averaged.
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 or AGENTS.md sections, rules, .claudeignore / .cursorignore, 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 |
--harness | auto (default), claude, cursor, or both. Scores are never averaged; --min-score gates each harness separately. --fix repairs Launchpad-managed files for every selected harness. |
Claude 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. |
Cursor analyzers
doctor --harness cursor (or auto when AGENTS.md, .cursor/hooks.json, or .cursor/rules/*.mdc exist) scores a separate report. A bare .cursor/ directory from the Cursor IDE is not enough.
| Analyzer | What it catches |
|---|---|
| Instructions | Missing AGENTS.md, instruction budget (~200 lines), missing sections (stack, commands, conventions, guardrails). Overflow belongs in .cursor/rules/*.mdc. |
| Hooks | Missing or stale Launchpad hook scripts, structurally bad hooks.json, fail-closed .env and destructive-shell hooks. |
| Rules | Missing or stale verification.mdc, missing YAML globs: frontmatter. |
| Security | .env missing from .cursorignore. |
| MCP | Unreadable .cursor/mcp.json or invalid mcpServers shape. |
--fix writes missing Launchpad-managed Cursor files, repairs stale hook scripts, migrates workflow-check onto postToolUse, and refuses to clobber a structurally invalid hooks.json.
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 or Cursor Agent to restructure the instruction file. 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 a manual CLAUDE.md / AGENTS.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 coding-agent setup
Scaffold Claude Code or local Cursor Agent config in seconds: instruction file, security hooks, permissions, verification rules, backlog workflow, and a code-reviewer agent — auto-detected for your stack.
eval — Test your coding-agent config
Run Claude Code or Cursor Agent against 17 test scenarios in isolated sandboxes and prove your instruction file, hooks, and permissions actually change behavior.