cursor-doctor

March 6, 2026 · View on GitHub

Your Cursor rules have bugs. This finds them.

You wrote rules. Cursor still ignores them. cursor-doctor tells you exactly what's wrong: conflicting directives, broken globs, vague instructions the AI can't act on, token budget waste, and 100+ other issues. One command. Zero dependencies.

npx cursor-doctor scan

cursor-doctor scan demo

🔧 Auto-fix everything: npx cursor-doctor fix — first 3 fixes free, Pro for all

What you get

  ▒▒ Cursor Health: B ▒▒

  ██████████████████████████░░░░  84%

  ✗ Conflict: "always use semicolons" vs "omit semicolons" in 2 files
  ✗ Glob *.tsx doesn't match any files in your project
  ⚠ 3 rules use alwaysApply — burning 2,400 tokens on every request
  ⚠ "write clean code" is too vague for the AI to act on
  ✓ Frontmatter valid across 12 rules
  ✓ No legacy .cursorrules detected

  8 passed  4 issues  (2 auto-fixable)

Not generic warnings. Issues specific to your rules, with the exact file and line.

Why this exists

We scanned 50 real open-source projects and found that 82% had at least one broken or misconfigured rule. The most common issues: contradictory instructions across files, glob patterns that match nothing, and vague rules the AI silently ignores.

Commands

Command	What it does	Free?
`npx cursor-doctor scan`	Health check with letter grade	✅
`npx cursor-doctor lint`	Rule-by-rule detailed diagnostics	✅
`npx cursor-doctor check`	CI pass/fail (exit code 0 or 1)	✅
`npx cursor-doctor badge`	Generate README badge snippets	✅
`npx cursor-doctor init`	Generate starter rules for your stack	✅
`npx cursor-doctor install react`	Install community rule packs	✅
`npx cursor-doctor fix --preview`	Preview auto-fixes before applying	✅
`npx cursor-doctor fix`	Apply all auto-fixes	3 free / Pro for unlimited
`npx cursor-doctor audit`	Full diagnostic report	Pro
`npx cursor-doctor conflicts`	Cross-format conflict detection	Pro
`npx cursor-doctor test <file>`	AI rule adherence testing	Pro
`npx cursor-doctor team drift`	Detect config drift across team	Pro

What it checks

100+ lint rules:

Conflicts — contradictory instructions across files (48 semantic patterns)
Syntax — broken YAML frontmatter, boolean strings, unclosed code blocks
Token budget — rules burning context window, dead rules, excessive alwaysApply
Globs — patterns that don't match files, regex in globs, overlapping coverage
Prompt quality — vague instructions, first person, politeness tokens, negation-only rules
Structure — file naming, duplicate content, missing descriptions, legacy .cursorrules

Auto-fix (Pro)

34 auto-fixers: frontmatter repair, glob syntax, boolean strings, whitespace, TODO removal, duplicate descriptions, heading normalization, and more.

npx cursor-doctor fix --preview    # See what would change (free)
npx cursor-doctor fix              # Apply all fixes (Pro)

$9 one-time at nedcodes.gumroad.com/l/cursor-doctor-pro. If it doesn't find real, fixable issues in your project, email hello@nedcodes.dev for a full refund.

VS Code / Cursor extension

Search "Cursor Doctor" in the extensions panel. Health grade in your status bar. Inline diagnostics on save. Quick-fix code actions with Pro.

CI / GitHub Action

Catch broken rules before merge:

- uses: nedcodes-ok/cursor-doctor@v1

Pre-commit hook

Validate rules locally before every commit:

cp scripts/pre-commit-hook.sh .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

The hook runs cursor-doctor check only when .mdc, .cursorrules, CLAUDE.md, or AGENTS.md files are staged.

README Badge

Show your project's Cursor rules health in your README:

npx cursor-doctor badge

Output:

Markdown:
  ![Cursor Rules: A (96%)](https://img.shields.io/badge/Cursor%20Rules-A%20(96%25)-brightgreen)

HTML:
  <img src="https://img.shields.io/badge/Cursor%20Rules-A%20(96%25)-brightgreen" alt="Cursor Rules: A (96%)">

Example:

Dynamic badge (updates automatically via shields.io endpoint):

# Generate endpoint JSON
npx cursor-doctor badge --json > cursor-rules-badge.json

# Commit to your repo
git add cursor-rules-badge.json && git commit -m "chore: add cursor rules health badge"

# Use in README.md (replace YOUR_REPO_URL)
![Cursor Rules Health](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/YOUR_REPO_URL/main/cursor-rules-badge.json)

Badge colors: A=brightgreen, B=green, C=yellow, D=orange, F=red.

MCP Server

Use cursor-doctor as an MCP tool inside your AI coding assistant:

{
  "mcpServers": {
    "cursor-doctor": {
      "command": "npx",
      "args": ["-y", "cursor-doctor-mcp"]
    }
  }
}

LSP Server

Real-time diagnostics in Neovim, Zed, or any LSP-compatible editor:

npm install -g cursor-doctor
# Configure your editor to use cursor-doctor-lsp

Tool	What	Install
rule-gen	Generate rules from your codebase with AI	`npx rulegen-ai`
rule-porter	Convert rules between Cursor, Claude, Copilot, Windsurf	`npx rule-porter`
nedcodes.dev	Guides, playground, and tools for Cursor AI developers

Like cursor-doctor?

If cursor-doctor helps your team ship better AI-assisted code, here's how to support it:

⭐ Star the repo — helps other developers find it
🐛 Report bugs — we fix issues fast
💬 Join the discussion — share patterns, request features, help others
📢 Share it — if it saved you debugging time, tell your team
🔧 Explore the ecosystem — rule-gen generates rules from your codebase, rule-porter converts between AI assistants, cursor-lint catches rule issues in real-time

License

MIT