cursor-doctor

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

🔧 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

Related tools

| 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