Every agent tool wants its own config file. CLAUDE.md for Claude Code, AGENTS.md for Codex and 30+ others, .cursor/rules for Cursor, .windsurfrules, GEMINI.md, copilot-instructions.md. You write a rule once, paste it into five places, and six months later the files disagree. One says npm, another says pnpm. One says never push to main, another says always.
There are good sync tools (rulesync) but they ask you to adopt a new source-of-truth format. I wanted a linter, not a migration: audit the files I already have.
So I built ruleherd. npx ruleherd reads every instruction file in a repo and reports:
- CONFLICT: contradictions between files (tabs vs spaces, npm vs pnpm, never vs always on shared topics)
- DEAD REF: backticked paths and @imports pointing at files that don't exist
- DEAD CMD:
npm run xwhere no package.json has an x script - STALE: "react 17" in the rules while package.json installs react 19
- DEAD GLOB: a .mdc rule whose globs point at a deleted directory (Cursor silently never loads it)
- DUPLICATE: paragraphs pasted across files
- BLOAT: single files over ~4k tokens that load into every prompt
Score out of 100. Strict mode exits nonzero for CI. Zero dependencies.
Real output on my own machine (it scans global configs too):
GRADE: B (85/100)
9 instruction files · ~4,757 tokens of agent context
DUPLICATE ~333-char block in 6 files
DUPLICATE ~939-char block in 6 files
DUPLICATE ~705-char block in 6 files
~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md,
~/.config/devin/AGENTS.md, windsurf global rules,
~/.agents/rules/, ~/.cursor/rules/browser-tooling.mdc
I hand-sync one universal rules file into five tool locations. It drifted anyway.
The embarrassing part: my first version flagged @types/node as a dead file reference and pnpm install as a missing npm script. Both are in my own config files. Auditing the auditor is humbling.
Honest limits: contradiction detection is heuristic (keyword pairs and never/always polarity, not semantic understanding). Dead-ref checking is deliberately conservative. A clean grade means "no detectable drift", not "your rules are good".
MIT, zero deps: https://github.com/princejain756/ruleherd
Which of your agent config files do you think is the stale one?
Top comments (3)
funny, npm in one file and pnpm in the other. When ruleherd finds a conflict, does it tell you which file is right, or is that on you? From my experience building Voiden around plain Markdown files, I'd rather have one source file the others point to than six copies to keep in sync.
Keep one source file and generate the others, then fail CI when a generated copy drifts. Two hand-edited files drift eventually, whatever tool reads them. Does ruleherd flag a conflict, or only show the diff?
The drift that hurts most here is not a contradiction but an omission: a rule added to one file after an incident and never copied to the others, so one tool keeps repeating the mistake the rest stopped making. Near-duplicate blocks where one copy has an extra line are a cheap signal for that, and keyword-pair checks would not flag them.