Detect stale references and context rot in your AGENTS.md, CLAUDE.md, and AI memory files.
$ npx agents-lint
agents-lint v0.7.0
────────────────────────────────────────────────────────────
Found 3 context files: AGENTS.md, CLAUDE.md, ~/.claude/projects/my-repo/memory/MEMORY.md
File: AGENTS.md · 100/100 (A)
✓ No issues
File: CLAUDE.md · 42/100 (F)
✖ Path does not exist: "./src/services/auth"
→ Remove this reference or update to the correct path.
⚠ References NgModules — Angular 14+ uses standalone components
→ Update CLAUDE.md to reflect standalone component architecture.
File: ~/.claude/.../memory/MEMORY.md · 85/100 (B)
✖ Memory index link broken: old-project-notes.md
→ "old-project-notes.md" no longer exists. Remove this entry or update the link.
Cross-File Consistency (1 issue)
ℹ Path "./src/payments" referenced in AGENTS.md but not in CLAUDE.md
→ Consider documenting in all context files, or run --fix to suppress.
────────────────────────────────────────────────────────────
Overall: 71/100 · 2 errors 1 warning 1 info
Detect stale references and context rot in AGENTS.md files. Keep your AI coding agents accurate and cost-efficient.
2026-11-15
Estrelas
—
Ferramentas
—
Disponibilidade
—
Why this exists
AGENTS.md files rot. You write them once, then the codebase evolves — directories move, scripts rename, dependencies change — and the file silently misleads your AI coding agents.
Two 2026 research papers confirmed what many teams had noticed:
"LLM-generated context files reduced task success by 2–3% while increasing cost by over 20%" — ETH Zurich, ICSE 2026
"None of the major coding agents expose the lifecycle hooks to make this architecture easy to build. That's a tooling gap waiting to be filled." — Addy Osmani, Google
agents-lint fills that gap. It's a zero-dependency CLI that verifies your AGENTS.md, CLAUDE.md, and AI memory files stay accurate as your repo evolves.
Installation
# Run once (no install)
npx agents-lint
# Install globally
npm install -g agents-lint
# Install as a dev dependency
npm install --save-dev agents-lint
Usage
# Generate a starter AGENTS.md for this project
agents-lint init
# Lint all context files in the current directory (auto-detected)
agents-lint
# Lint a specific file
agents-lint ./docs/AGENTS.md
# Interactive fix mode — review and apply suggested fixes
agents-lint --fix
# Fail CI if any errors found
agents-lint --max-warnings 0
# JSON output for tooling
agents-lint --format json > report.json
# Quiet mode (errors only)
agents-lint --quiet
Verifies every path mentioned in your context files (./src/services, ./packages/ui, etc.) still exists on disk.
⚙️ npm Scripts
Validates that npm run <script> commands referenced in your file are present in package.json. Works with workspaces and monorepos.
🔨 Make Targets
Validates that `make <target>` commands referenced in your file name a target actually defined in the repo's Makefile (the Make/Go analogue of the npm-scripts check). Only backtick-quoted references are checked, so prose like "make sure" is never mistaken for a target. A `make forms-*` family reference is satisfied by any defined target sharing that prefix. No Makefile → the check is skipped.
📦 Dependencies
Detects references to packages not in package.json, and flags deprecated packages (moment, request, tslint, etc.).
🏗️ Framework Staleness
Catches outdated patterns for your detected framework:
Framework
Example check
Angular
@NgModule in an Angular 14+ project
Angular
@Input()/@Output() decorators (prefer signal-based input()/output() in Angular 17+)
Angular
::ng-deep (deprecated Angular 14+)
Angular
Constructor injection (prefer inject() in Angular 17+)
The weekly schedule is intentional — context rot happens even when your context files haven't changed, because your codebase evolves around them.
Quick start: agents-lint init
Generate a well-structured starter file based on your project's detected stack:
npx agents-lint init
This creates AGENTS.md with sections for Setup, Structure, Testing, Build, and Conventions — pre-populated from your package.json. Fill in the TODO comments, then run agents-lint to validate.
Custom rules (.agents-lint.json)
Place .agents-lint.json in your repo root to override defaults:
Substrings — matching paths/deps are skipped in all checks including cross-file
severity.missingPath
error|warn|info
Override severity for missing filesystem paths (default: error)
severity.missingScript
error|warn|info
Override for missing npm scripts (default: warn)
severity.missingMakeTarget
error|warn|info
Override for missing Makefile targets (default: error)
severity.staleDependency
error|warn|info
Override for deprecated packages (default: info)
severity.missingSection
error|warn|info
Override for missing recommended sections (default: warn)
Programmatic API
import { lint, lintAll } from 'agents-lint';
// Lint a single file
const report = await lint({
filePath: './AGENTS.md', // optional, auto-detected
repoRoot: process.cwd(), // optional
});
console.log(report.score); // 0–100
console.log(report.errors); // number of errors
console.log(report.results); // per-checker detailed results
// Lint all detected files (including Claude memory files)
const multi = await lintAll({ repoRoot: process.cwd() });
console.log(multi.overallScore); // combined score
console.log(multi.crossCheck); // cross-file consistency results
console.log(multi.files); // list of detected files
CLI Reference
USAGE
agents-lint [file] [options]
agents-lint init
COMMANDS
init Generate a starter AGENTS.md for this project
OPTIONS
--root <path> Repository root (default: cwd)
--fix Interactive mode: review and apply suggested fixes
--format <fmt> text | json (default: text)
--max-warnings <n> Exit with error code 1 if warnings exceed n
--quiet Only show errors
--no-color Disable colored output
--help Show help
--version Show version
EXIT CODES
0 No issues found
1 Warnings or errors found
2 Fatal error (file not found)
Roadmap
--fix mode: interactive suggestions for updating stale references and cross-file issues
agents-lint init — generate a well-structured AGENTS.md from scratch
Support for CLAUDE.md, GEMINI.md, .cursorrules, COPILOT.md
Claude Code memory file support — auto-detect and validate ~/.claude/projects/*/memory/
Cross-file consistency checks across multiple context files
Custom rules via .agents-lint.json config
VS Code extension with inline diagnostics
Git-blame integration: flag sections that haven't been touched in > 90 days
Contributing
git clone https://github.com/giacomo/agents-lint
cd agents-lint
npm install
npm run build
node dist/cli.js # test against this repo's own context files
npm test # run the test suite (62 tests, no extra dependencies)
Issues and PRs welcome. If you have a checker idea, open an issue first so we can discuss the design.
Background
The AGENTS.md standard was contributed to the Agentic AI Foundation (Linux Foundation) by Anthropic, OpenAI, and Block in late 2025. It's now used by 60,000+ open-source projects.
As adoption grew, so did the problem of stale context. This tool exists to solve that — automatically, in CI, before your agents start giving expensive wrong answers.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Agents Lint?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Agents Lint precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Agents Lint usa?
Agents Lint roda localmente via stdio.
Quando Agents Lint foi verificado pela última vez?
Última verificação: 2026-11-15. Detect stale references and context rot in AGENTS.md files. Keep your AI coding agents accurate and cost-efficient.