agents-lint

Detect stale references and context rot in your AGENTS.md, CLAUDE.md, and AI memory files.

$ npx agents-lint

agents-lint v0.5.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

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

Add to package.json

{
  "scripts": {
    "lint:agents": "agents-lint --max-warnings 5"
  }
}

What it checks

📁 Filesystem

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.

📦 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+)
Angular	`NgClass`/`NgStyle` directives (prefer native class/style bindings)
React	`ReactDOM.render()` (removed in React 19)
React	Class component lifecycle methods
Next.js	`getInitialProps` (legacy API)
Node.js	CommonJS in ESM projects
Symfony	`SwiftMailer` (removed in Symfony 6), `@Route` annotations, `FOSUserBundle`
Laravel	String-based routing, `make:auth`, `str_singular()`/`str_plural()`
Django	`django.conf.urls.url()`, `ugettext`, `force_text` (all removed in Django 4.0)
Zend	Any `Zend_`/`ZendFramework` reference (abandoned 2019, superseded by Laminas)
PHP (any)	`mailhog` references (unmaintained, replaced by Mailpit)

📋 Structure

Checks for recommended sections (Setup, Testing, Build) and quality indicators:

File too short (< 100 chars) or too long (> 15,000 chars — costs 20%+ more)
Unresolved TODO/FIXME markers
References to years before 2024

🔗 Cross-File Consistency

When multiple context files are detected, checks for conflicts between them:

Package manager conflict — one file says npm, another says yarn (error)
Script role conflict — different test or build commands across files (warning)
Path asymmetry — a significant path mentioned in one file but missing from others (info)

🧠 Claude Memory Files

Validates Claude Code memory files (auto-detected from ~/.claude/projects/<repo>/memory/):

Broken index links — MEMORY.md entries pointing to files that no longer exist (error)
Missing frontmatter — individual memory entries missing the --- block (error)
Invalid memory type — type: must be user, feedback, project, or reference (warning)
Missing required fields — name and description must be present in frontmatter (warning)

Freshness Score

Every run produces a score from 0 to 100:

Score	Grade	Meaning
90–100	A	Context files are fresh and accurate
80–89	B	Minor issues, still reliable
70–79	C	Some stale references
50–69	D	Significant context rot
0–49	F	Agents may produce incorrect or costly outputs

Errors cost 15 points, warnings 7, infos 2.

Supported file names

agents-lint auto-detects any of these in the repo root and from your Claude Code memory directory:

File	Used by
`AGENTS.md`	Codex, general
`CLAUDE.md`	Claude Code
`GEMINI.md`	Gemini CLI
`COPILOT.md`	GitHub Copilot
`.cursorrules`	Cursor
`.github/copilot-instructions.md`	GitHub Copilot
`.claude/MEMORY.md`	Claude Code (project-local)
`~/.claude/projects/<repo>/memory/*.md`	Claude Code (user memory)

The Claude user memory directory is automatically derived from your repo path — no configuration needed.

Pass an explicit path to lint any file: agents-lint ~/.claude/projects/my-repo/memory/MEMORY.md

Interactive fix mode

Run agents-lint --fix to review and apply suggested fixes one at a time:

agents-lint — Fix Mode
────────────────────────────────────────────────────────────
Cross-file issues  ·  1 fixable, 0 advisory

Issue 1/1  [fixable]
  ℹ Path "src/tests/helpers.ts" referenced in AGENTS.md but not in CLAUDE.md

  Fix: Add "src/tests/helpers.ts" to ignorePatterns in .agents-lint.json

  Apply? (y)es / (n)o / (q)uit  › y
  ✓ Will add to ignorePatterns

────────────────────────────────────────────────────────────
✓ Updated .agents-lint.json — added 1 pattern to ignorePatterns

Fix mode handles:

Stale path references — remove the line
Missing sections — append a template section
Cross-file path asymmetry — add the path to ignorePatterns in .agents-lint.json

GitHub Actions

# .github/workflows/agents-lint.yml
name: agents-lint
on:
  push:
    paths: ['AGENTS.md', 'CLAUDE.md', 'package.json']
  schedule:
    - cron: '0 9 * * 1'  # Weekly — catch silent rot

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx agents-lint --max-warnings 5

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:

{
  "requiredSections": ["Architecture", "Deployment"],
  "ignorePatterns": ["./legacy", "node_modules", "src/tests/helpers.ts"],
  "severity": {
    "missingPath": "warn",
    "missingScript": "error",
    "staleDependency": "warn",
    "missingSection": "error"
  }
}

Option	Type	Description
`requiredSections`	`string[]`	Extra section names that must exist
`ignorePatterns`	`string[]`	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.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.

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.claude		.claude
.github/workflows		.github/workflows
scripts		scripts
src		src
.agents-lint.json		.agents-lint.json
.gitignore		.gitignore
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
landing.html		landing.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

agents-lint

Why this exists

Installation

Usage

Add to package.json

What it checks

📁 Filesystem

⚙️ npm Scripts

📦 Dependencies

🏗️ Framework Staleness

📋 Structure

🔗 Cross-File Consistency

🧠 Claude Memory Files

Freshness Score

Supported file names

Interactive fix mode

GitHub Actions

Quick start: `agents-lint init`

Custom rules (`.agents-lint.json`)

Programmatic API

CLI Reference

Roadmap

Contributing

Background

License

About

Uh oh!

Releases 5

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

agents-lint

Why this exists

Installation

Usage

Add to package.json

What it checks

📁 Filesystem

⚙️ npm Scripts

📦 Dependencies

🏗️ Framework Staleness

📋 Structure

🔗 Cross-File Consistency

🧠 Claude Memory Files

Freshness Score

Supported file names

Interactive fix mode

GitHub Actions

Quick start: agents-lint init

Custom rules (.agents-lint.json)

Programmatic API

CLI Reference

Roadmap

Contributing

Background

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Quick start: `agents-lint init`

Custom rules (`.agents-lint.json`)

Packages