Show HN: Agents-lint – detect stale paths and context rot in AGENTS.md files

1 point

3 months ago

AGENTS.md (and CLAUDE.md, GEMINI.md, .cursorrules) has become the standard way to tell AI coding agents how your repo works. It's now in 60,000+ repos. Codex, Claude Code, and Gemini CLI read these files before every task.

The problem: nobody keeps them up to date.

Paths get renamed. npm scripts change. Framework patterns go stale. The file that was accurate when you wrote it in September starts giving your agents wrong instructions by December — without a single commit to AGENTS.md.

An ETH Zurich study presented at ICSE 2026 put numbers on this: stale context files reduced agent task success by 2–3% while increasing token costs by over 20%.

agents-lint is a zero-dependency CLI that catches this automatically:

  npx agents-lint

It runs five independent checks: 1. Filesystem — every path mentioned in your file is verified to exist 2. npm scripts — every `npm run <script>` is verified against package.json (workspace-aware) 3. Dependencies — deprecated packages (moment, request, tslint) are flagged 4. Framework staleness — Angular NgModules in Angular 14+, ReactDOM.render() in React 19, getInitialProps in Next.js App Router, CommonJS in ESM projects 5. Structure — recommended sections, bloat (>15k chars adds 20% token cost), unresolved TODOs, old year references

Every run produces a freshness score (0–100). The real value is adding it to CI with a weekly schedule — because context rot happens even when the file hasn't changed:

  schedule:
    - cron: '0 9 * * 1'  # Every Monday

That weekly schedule is the whole point. Your AGENTS.md can rot without a single commit to it.

When multiple agent config files exist (AGENTS.md + CLAUDE.md, etc.), it also cross-checks them for conflicting instructions — e.g. one file says `npm run test`, the other says `npm run test:unit`.

What I found when testing on real repos: absolute home-directory paths that only work on the author's machine, monorepo commands copy-pasted into single-package projects, and framework references to APIs removed two major versions ago. All silently misleading agents on every task.

Landing page: https://giacomo.github.io/agents-lint/ npm: https://www.npmjs.com/package/agents-lint

Would love feedback — especially if you find unexpected issues in your own AGENTS.md.

1 comment