cursor-lint started as a thing I built because my own .mdc rules kept silently breaking. Missing frontmatter, bad YAML, alwaysApply not set. Cursor doesn't tell you when a rule fails to load. It just... doesn't load it. No error, no warning, nothing.
That tool ended up getting ~1,800 downloads, which was cool, but I kept running into problems it couldn't solve. Like, I had two rules that contradicted each other ("use semicolons" in one file, "avoid semicolons" in another) and the linter had no way to catch that. Or I'd have rules with 80% identical content because I'd copy-pasted and forgotten to clean up. The linter could tell me if individual rules were well-formed, but it couldn't tell me if my setup was healthy.
So I rebuilt it.
cursor-doctor
npx cursor-doctor scan
The free scan gives you a health grade (A through F) based on 8 checks: whether rules exist, legacy .cursorrules conflicts, 20+ lint checks, token budget, file type coverage, file sizes, alwaysApply usage, and whether you have agent skills set up.
It looks like this:
Cursor Health: C (62%)
──────────────────────────────────
✓ Rules exist
✗ No legacy .cursorrules
! Token budget: ~4,200 tokens — getting heavy
✓ Coverage: Rules cover your project file types
Zero dependencies, runs straight from npx.
The stuff that was actually hard to build
Conflict detection. This was the main thing I wanted. The tool extracts directives from your rule bodies ("use X", "prefer X", "never X", "avoid X") and compares them across files. If one rule says "always use trailing commas" and another says "remove trailing commas," it flags it. It's not just 9 hardcoded regex patterns anymore. It understands the intent of the instruction.
Redundancy detection. Compares line overlap between rules. If two files share more than 60% of their content, that's wasted context window. Every redundant token is a token not being used for your actual code.
Stack detection. Reads your package.json, requirements.txt, pyproject.toml, Cargo.toml, etc. and figures out what you're using. Knows about 12+ frameworks (React, Next.js, Django, Express, Vue, Svelte, and more) and 6 languages. If you're running a Next.js project with no Next.js-specific rules, it tells you.
Pro ($9, one-time)
The free scan shows you what's wrong. Pro fixes it.
cursor-doctor audit gives you the full diagnostic: conflicts, redundancy analysis, token budget breakdown (always-loaded vs conditional), stack-specific gap analysis, and concrete fix instructions. audit --md exports it as markdown you can share with your team or drop in a PR.
cursor-doctor fix actually repairs things. It auto-merges redundant rules, fixes broken YAML frontmatter, splits oversized files, and generates starter rules for your detected stack. There are templates for React, Next.js, Python, Django, Go, Rust, Vue, Svelte, Tailwind, Express, and testing. fix --dry-run previews everything before writing.
# Activate after purchase
cursor-doctor activate <your-key>
Links
If you've been using cursor-lint, cursor-doctor includes everything it did plus all the diagnostic and repair stuff. Different package name though, so npx cursor-doctor is what you want now.
Top comments (3)
The fact that Cursor silently fails to load broken rules — no error, no warning, nothing — is such a perfect illustration of why methodology needs to be code, not just config files you hope the tool reads correctly.
The contradiction detection is the killer feature here. I've hit exactly that problem: two rules that evolved independently end up conflicting, and you don't notice until the AI output is inconsistent and you spend 20 minutes figuring out why.
This also highlights the portability problem. Your .mdc rules are Cursor-specific. If you switch to Claude Code or Copilot tomorrow, all the knowledge encoded in those rules needs to be re-expressed in a different format. The diagnostic tool is great for Cursor, but the underlying insight — that your AI instructions need version control, testing, and consistency checks — applies across every tool.
Have you thought about an export/convert feature? Something that could take validated Cursor rules and output an equivalent AGENTS.md or CLAUDE.md? That'd solve a real pain point for people working across multiple tools.
Yeah, I think it's ridiculous that you can have a perfectly written rule that does nothing because of a frontmatter typo, and Cursor won't tell you. Regarding contradictions, many rules overlap in scope with slightly different instructions, and the AI just picks one unpredictably. It's been tricky to figure that part out.
The export/convert idea is interesting. Right now cursor-doctor already parses the full rule structure (frontmatter, globs, description, body), so the data model is there. But it doesn't map Cursor-specific concepts like alwaysApply and glob patterns to how other tools scope their instructions. AGENTS.md is flat markdown, CLAUDE.md is similar but with different conventions. It's not a 1:1 translation but it's doable for the common cases. I'm going to look into this and see about adding it. Thank you for flagging.
The conflict detection is the killer feature here. I've hit exactly that problem — two rule files contradicting each other, and Cursor just silently picks one (or worse, alternates between them depending on which file it reads first).
This is actually a great example of why methodology should be code, not documentation. When your coding conventions are in rule files, you can lint them, diff them, detect conflicts programmatically. When they're in a team wiki or someone's head, contradictions live forever undetected.
The token budget tracking is underrated too. I've seen people write 2,000-token rule files that eat into their context window for every single prompt. That's context the model could have used for your actual code. Your health grade approach — making it visible that rules have a cost — should change how people think about what goes in those files.