manishrawal95/check-agent-docs

Checks that your CLAUDE.md, AGENTS.md and other agent instruction files still match your code. When a file moves, a script is renamed or the package manager changes and the instructions don't follow, it tells you which line is wrong and where the thing went.
$ check-agent-docs
src/pydanticclai2/AGENTS.md:315 [moved] tests/menuscript.py
The scripted menu runner lives at tests/clai2/menuscript.py, not at tests/menuscript.py.
fix: tests/clai2/menuscript.py
AGENTS.md:43 [other] make lint # mypy type checking
make lint runs ruff and its recipe says no type checker is configured; it is not a mypy run.
12 instruction file(s), 2 issue(s), 0.9s
It reads CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules/, .cursorrules, .github/copilot-instructions.md, .github/instructions/, .windsurfrules, .windsurf/rules/ and .clinerules (file or folder) in one pass.
## Why
Agents follow these files literally. When code moves and the instructions don't, the agent goes looking for a folder that isn't there, runs a script that was renamed, or installs with the wrong package manager. In tests on 216 popular open-source repos with agent files, 54 (1 in 4) had at least one instruction that was wrong at the current commit.
## How it works
1. Local checks (fast, no network, no AI). Every path, file name, folder-tree diagram, script, task, make/just target and install command is checked against the repo with git: tracked and staged files, every .gitignore, submodules, symlinked folders, the nearest lockfile, package.json, pyproject.toml (project scripts, poe, pdm, hatch), Makefiles (including Makefile.), justfiles, Taskfiles, deno.json, turbo and mise. This takes about 0.1 s per repo, and --fix rewrites moved paths in place.
2. AI review (optional, experimental). With ANTHROPICAPIKEY set, a small model reads each flagged instruction file next to those facts, including what each mentioned command really runs, and reports only claims that would mislead an agent. It skips examples, placeholders, files you're told to create, other repos and gitignored paths. Files where every claim checked out are never sent, results are cached, and requests run in parallel. Read How good is it? before relying on it.
## Use it in Claude Code (plugin)
/plugin marketplace add manishrawal95/check-agent-docs
/plugin install check-agent-docs@check-agent-docs-marketplace
/check-agent-docs:check checks every instruction file. Use --fix to rewrite moved paths, --changed origin/main for a branch, or --only CLAUDE.md for one file. The review is done by Claude in your session, or by the bundled instruction-reviewer subagent, so no API key is needed. The tool still applies its guard rails to the answers.
Automatic check after edits: when Claude edits an instruction file, a hook runs the local checks (about 0.1 s, no network) and tells Claude about any path, script or target that doesn't exist.
To try it from a local copy: claude --plugin-dir ./check-agent-docs.
## Install the CLI
A single Python file with no dependencies (Python 3.10+; 3.11+ for pyproject.toml tasks).
bash
pipx install git+https://github.com/manishrawal95/check-agent-docs
# or copy checkagentdocs.py into your repo and run: python3 checkagentdocs.py