← back to Agent Instructions Drift Check
Reading an instructions file and clicking through its links is a normal way to catch drift once, and it works fine for a short file checked right after you edit it. It is a different job from confirming the file is still accurate today, after every commit that touched anything the file names -- most of which nobody thinks to re-check, because they didn't touch the instructions file itself.
| Step | Common gap by hand | What this checker does |
|---|---|---|
| Confirming every file reference still resolves | Click through the links you remember are there; a file that grew over months has references nobody has looked at in a while, and a rename elsewhere in the repo doesn't prompt anyone to go back and check them. | Resolves every markdown link and inline-code path reference against your actual repo in one pass, every time you run it. |
| Confirming every npm script reference is still defined | Run the ones you remember to test; a script renamed in an unrelated refactor a month later silently makes an older reference stale with nothing prompting a re-check. | Checks every npm run, npm test, and npm start reference against package.json's scripts map in the same pass. |
Spotting a bare pytest or mypy | Requires already knowing the specific interpreter-mismatch footgun exists; without that context, a bare tool name and a python3 -m-prefixed one read as interchangeable phrasing during a skim. | Flags a bare pytest or mypy in a fenced code block by rule, every time, regardless of whether the reader already knows why it matters. |
| Re-checking after later, unrelated changes | Nothing prompts a re-check of a paragraph you didn't just edit -- drift accumulates silently between the checks that do happen. | Costs nothing to re-run; wiring the CLI into CI on every PR makes the re-check automatic rather than something to remember. |
| Is anything I check uploaded anywhere? | N/A | No. Runs entirely in your browser; the CLI makes no network call. |
Nothing, for a short file, checked once. It stops scaling the way these files actually grow: a CLAUDE.md or AGENTS.md that accumulates dozens of file references and npm-script mentions over months means clicking through all of them, correctly, every time anything else in the repo moves -- and nobody re-checks a paragraph they didn't just edit. This tool resolves every reference in the file the same way, every time you run it, in the time it takes to paste the file in.
It confirms the scripts that exist today. It does not get re-run the next time a script gets renamed in an unrelated PR, so the instructions file drifts again as soon as you stop checking -- which is exactly when an agent following it hits the stale name. This tool checks every npm run reference against package.json's scripts map in one pass, so re-checking after any change costs nothing extra.
Only if the reviewer already knows the specific footgun exists -- that an isolated tool install (a uv tool install, a pipx install) can put pytest or mypy on PATH pointed at a different interpreter than the repo's own dependencies. Without that context, pytest tests -q and python3 -m pytest tests -q read as interchangeable phrasing, not a real difference, and the one-word gap is easy to skim past even for someone looking. This tool applies the same two rules every time, so it does not depend on the reviewer already knowing the failure mode.
No. The browser page parses the text you paste and the file names it reads from a folder you pick entirely in your own browser, and never sends any of it anywhere -- exactly like the rest of this tool. The CLI reads only local files, with no network call, ever.
node cli.mjs check AGENTS.md
node cli.mjs check CLAUDE.md --package package.jsonExits 1 if anything is found, so it works as a CI gate on the same PR that renames a file or a script. See why these files rot, and this checker's own named limits.