HN Showcase
Back to browse
GitHub Repository

Your AGENTS.md is probably lying. Detect stale paths, dead npm scripts, outdated framework patterns, and context rot before they make your coding agents expensive and wrong.

8 starsTypeScript

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

by devGiacomo·Feb 28, 2026·1 point·1 comment
Visit ProjectView on HN

AI Analysis

●●●BangerSolve My ProblemZero to One

Closes a real AI tooling gap: detects stale AGENTS.md before agents waste tokens on wrong instructions.

Strengths
  • •Backs claims with ICSE 2026 research (2–3% task success loss + 20% cost inflation from stale context)
  • •Framework-aware checks (Angular standalone components, npm workspaces) go beyond simple path validation
  • •Zero dependencies, CLI-first, works in any CI—low friction adoption
Weaknesses
  • •Still early (v0.2.0); AGENTS.md standardization itself is months old, ecosystem risk real
  • •No auto-fix in repo yet despite promise in --fix flag; manual remediation required
Target Audience

Teams using AGENTS.md files with Claude Code, Codex, or Gemini; CI/CD pipeline operators

Similar To

ESLint (pattern: linting + framework awareness) · Trivy (pattern: detecting risk in configs)

Post Description

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.

Similar Projects