CLAUDE.md, AGENTS.md and .cursorrules tell your
assistant which files to read. Those files move. Nothing errors — the
instruction just quietly stops meaning anything.
$ agents-sync ✗ broken-ref CLAUDE.md:3 docs/architeture.md — not found → docs/architecture.md (did you mean?) ✗ broken-ref CLAUDE.md:4 src/config.ts — not found → src/config/index.ts (moved — fixable) 2 broken-ref
Pointed at six public repositories carrying a CLAUDE.md, it reported three dead references and nothing else.
All three were real.
haddock3 moved docs/ to docs/pages/, leaving two
instructions pointing at files that no longer existed.
react-data-table-component converted api.md to
api.astro and kept telling its assistant to edit the old one.
The other four repositories came back clean — no noise.
A linter that cries wolf gets uninstalled. A reference is only reported when the tool can say something useful about it.
“read docs/architecture.md first” counts, the same as a backticked path,
a markdown link or a [[wikilink]]. Bracket syntax inside
backticks does not — [[redirects]] in a TOML note is a table
header, not a link.
Exact name elsewhere, same name with a new extension, a file that grew
into a folder (src/config.ts →
src/config/index.ts), a typo, or a plural.
Naming the tail of a path and leaving the root to context is something a reader follows without trouble, so it counts as resolved rather than broken.
A candidate has to live in a folder the reference actually names, so
notes/core.md is never “fixed” to a core.md
sitting in some cache directory.
A weekly background run raises a notification only when something new turns up — and the notification carries the fix.
The notification stays on screen until you deal with it, with Fix, Open report and Remind me tomorrow on it.
If the machine was off at the scheduled time, the run happens the next time you log in.
Findings are remembered between runs. Something you decided to live with stays quiet.
The HTML report says what each problem means and what it costs you, with a fix button per finding.
Zero dependencies, no build step. Node 18+.
git clone https://github.com/berkdemir18/agents-sync.git cd agents-sync npm link
| Command | What it does |
|---|---|
| agents-sync | Report problems. Exits 1 if it finds any, so it drops straight into CI. |
| agents-sync report | Build a self-contained HTML page you can actually look at. |
| agents-sync apply | Rewrite what is unambiguous, keeping a backup of every edited file. |
| agents-sync schedule | Run it weekly in the background (Windows). |