Lint Your CLAUDE.md and AGENTS.md Before Your Agent Does

A context file is the one document your agent reads before it reads anything else, and it is the one document nothing in your toolchain validates. Rename a directory and CLAUDE.md still points at the old one. Switch test runners and line 8 still says the old command. The agent does not notice the contradiction -- it follows the file, fails, and burns a few minutes of your attention proving that a markdown file was wrong. We have argued the problem before; this post is about the tools, including our own, npx -y @yawlabs/ctxlint.

The format is worth pinning down first. AGENTS.md describes itself as "a simple, open format for guiding coding agents", says it is now stewarded by the Agentic AI Foundation under the Linux Foundation, and claims use by over 60 thousand open-source projects. It is a filename convention with no schema, which is exactly why linting it is about the project rather than the markdown.

What a linter can mechanically check

Nothing here requires a model. Every one of these is a deterministic cross-reference between what the file claims and what the repository contains:

Paths that no longer exist. The single most common rot, and the easiest to fix automatically when git knows the file was renamed.
Commands that are not real. A documented npm test that does not exist in package.json scripts or a Makefile target.
Contradictions across files. One file says Vitest, another says Jest. The agent picks one, usually the wrong one.
Secrets pasted into context. Private-key headers and provider token shapes, reported without echoing the value.
Secrets in MCP configs. A hardcoded bearer token in a git-tracked .mcp.json is a different, worse version of the same mistake.
Dead hooks. A PreToolUse hook pointing at a script that no longer exists is a gate that silently passes everything.
Token cost. How much of the context window these files spend every single session, and which sections are redundant with what the agent can already infer from the manifest.

Run against a drifted repository, that produces something like this:

Found 2 context files (1,847 tokens total)
  CLAUDE.md (1,203 tokens, 42 lines)
  AGENTS.md -> CLAUDE.md (symlink)

CLAUDE.md
  x Line 12: src/auth/middleware.ts does not exist
    -> Did you mean src/middleware/auth.ts? (renamed 14 days ago)
  x Line 8: "pnpm test" -- script "test" not found in package.json
  ! Last updated 47 days ago. src/routes/ has 8 commits since.
  ! testing framework conflict: "Vitest" in CLAUDE.md vs "Jest" in AGENTS.md
  i Line 3: "Express" is in package.json dependencies -- agent can infer this

The half that is not markdown

The interesting checks have drifted away from prose. MCP client configs are context too: they decide what the agent can do, and they are where credentials end up. The rules there are fiddly and per-client -- .vscode/mcp.json uses servers as its root key where everyone else uses mcpServers, Cursor wants ${env:VAR} where Claude Code takes ${VAR}, Windows needs the cmd /c wrapper around npx, and SSE was deprecated in favour of Streamable HTTP. Our MCP configuration guide covers the shapes; a linter is how you keep them from rotting.

Then there is the agent's own state. Memory files accumulate entries pointing at paths that no longer exist, near-duplicate memories pile up across projects, and a MEMORY.md past the documented session-load cap quietly stops being loaded past that line. Those checks read outside the project directory, so they are opt-in in every tool that has them.

Wiring it in

A linter you run by hand once is a linter you run once. The four useful placements are a CI gate, a pre-commit hook, an editor, and the agent itself:

npx -y @yawlabs/ctxlint@latest            # report; exit 0 even when it finds issues
npx -y @yawlabs/ctxlint@latest --strict   # CI gate; exits 1 on any warning or error
npx -y @yawlabs/ctxlint@latest --mcp      # add the MCP config checks
npx -y @yawlabs/ctxlint@latest --fix      # rewrite broken paths from git history
npx -y @yawlabs/ctxlint@latest init       # install a git pre-commit hook
npx -y @yawlabs/ctxlint@latest serve      # run it as an MCP server

That last one is the inversion worth noticing: the agent lints its own context mid-session and fixes what it finds. Seven tools are exposed, six of them read-only and one (ctxlint_fix) declaring itself destructive because it writes to disk. Useful, but not a security control -- the MCP specification says "clients MUST consider tool annotations to be untrusted unless they come from trusted servers". For CI there is also SARIF output, which lands the findings in GitHub Code Scanning next to your other security results.

Six linters, compared

Every row below was read from the project's own repository, and the counts come from the machine-readable rule catalogs where the project publishes one. Versions and star counts are as of September 2026.

Tool	Scope	How it runs	License / notes
`@yawlabs/ctxlint`	41 context rules across 16 file formats, 29 MCP-config rules across 8 clients, 12 session and memory rules, 5 experimental skill rules	CLI, CI, pre-commit, MCP server; text, JSON and SARIF output	MIT, v0.24.1. Publishes its four rule catalogs as open specs
agnix	455 rules (counted in its own rule catalog) across 9 tools including Claude Code, Cursor, Copilot, Kiro, Gemini CLI, MCP and AGENTS.md	Rust CLI plus language server, MCP binary, VS Code / JetBrains / Neovim / Zed extensions, GitHub Action, browser playground	MIT or Apache-2.0, 410 stars. Installs via npm, Homebrew, pip or cargo
AgentLint	58 checks: 51 deterministic ones across six dimensions, plus 7 opt-in checks that use AI subagents or local session logs	Shell CLI, GitHub Action, opt-in Claude Code slash command; scores 0-100 and emits a fix plan	MIT, 56 stars. Covers harness files: workflow permissions, SHA-pinned actions, .gitignore
cclint	Claude Code project files: agent and slash-command frontmatter, settings.json hooks, CLAUDE.md structure	CLI with console, JSON or markdown reports; configurable failure threshold; Zod schema extension	MIT per its README, 22 stars. Last npm release 0.2.10 in September 2025
agents-lint	Paths, npm scripts, deprecated dependencies, framework-staleness patterns, structure, cross-file consistency, Claude memory files	Zero-dependency CLI, interactive fix mode, GitHub Action; 0-100 freshness score with a letter grade	MIT, 13 stars, v0.5.0
AgentLinter	Eight scoring dimensions including secrets, cross-file consistency, token budget, runtime config and skill safety	CLI with auto-fix, workspace templates, and export of a CLAUDE.md to Cursor, Copilot or Gemini formats	MIT, 80 stars
agents-md-cookbook	Templates per stack and a compatibility matrix, plus two CLIs: a linter and a migrator	Copy a template, migrate an existing file, lint in CI via npx or a bundled Action	MIT, 16 stars. Both CLIs at v1.0.1

Where the alternatives win

agnix is the one to beat on breadth and on editor integration. 455 rules is not marketing -- it is the length of the rules array in its published catalog -- and it is the only tool here that ships ready-made editor extensions for VS Code, JetBrains, Neovim and Zed, plus a language server, an MCP binary, and a playground you can paste a file into without installing anything. It also installs without Node, which matters on a Python or Rust team. If you want one linter for a mixed Claude Code plus Cursor plus Kiro shop and you want squiggles while you type, start there.

AgentLint asks a question the others do not. Its checks reach past the context file into the harness around it: are your GitHub Actions pinned to a SHA, does a workflow grant write permissions it does not need, is .env in .gitignore at all. It also produces a prioritised fix plan rather than a flat list, which is the right shape when you inherit a repository and need to know what to do first.

cclint goes deeper on one tool. If your repo is Claude-Code-only and full of custom subagents and slash commands, schema validation of that frontmatter against the documented fields -- with your own Zod extensions for project-specific keys -- is more useful than any amount of breadth. Its last npm release was September 2025, so check it still matches the current field set before relying on it in CI.

agents-lint has the nicest single idea. Framework staleness: flagging @NgModule in an Angular 14-plus project, or ReactDOM.render() after React 19 removed it. That is context rot nothing else here catches, it is zero-dependency, and the weekly-schedule GitHub Action in its README is the right instinct -- your context file rots when the code around it changes, not when you edit the file.

And if you do not have an AGENTS.md at all, start with agents-md-cookbook. A tested template plus a one-command migration from an existing CLAUDE.md or .cursorrules beats linting a file you have not written yet.

What none of them can check

Every tool here answers "is this file true?" and "is this file cheap?". None of them answers "is this file right?". A rule can point at a real path, name a real script, contradict nothing, cost 40 tokens, and still be bad advice that makes your agent worse. Deterministic linting is a floor, not a grade -- it removes the failures that waste your time so the remaining arguments are about content. That is also why the scoring tools in the table disagree with each other: a number out of 100 encodes somebody's opinion about weighting, and it is worth knowing whose.

The honest heuristic: run whichever one covers your stack in CI this week. The checks that catch real breakage -- dead paths, dead commands, secrets, contradictions -- are spread unevenly across these six rather than implemented by all of them, so read the scope column before you pick. But every one of them catches something nothing else in your toolchain checks at all, and the difference between having one and having none is far larger than the difference between any two of them.

Try it

Add it to any MCP client, or let Yaw MCP fan one config out to every client on the machine:

npx -y @yawlabs/ctxlint serve

The card is on our MCP servers page, and the source, the rule catalogs and the four lint specs are at github.com/YawLabs/ctxlint.

Frequently Asked Questions

Can a linter tell me whether my CLAUDE.md is any good?

It can tell you whether the file is true and whether it is cheap. A linter checks that every path exists, that every command is a real script, that two files do not contradict each other, and how many tokens the file costs per session. Whether a rule is good advice for your repo is a judgement no linter makes, so treat a clean run as a floor rather than a grade.

Do I need separate linters for AGENTS.md and CLAUDE.md?

No. Five of the six compared here read both, because the checks that matter are about the project rather than the filename; the exception is agents-md-cookbook, whose linter targets AGENTS.md while its separate migrator is what reads CLAUDE.md. What differs is the breadth beyond those two files: agent and command frontmatter, MCP client configs, hooks, skills, CI workflows, and agent memory directories are each covered by some tools and not others.

Is a context linter an MCP server?

It is a linter first. Some of them also ship an MCP server so an agent can lint its own context mid-session: ctxlint exposes seven tools through the serve subcommand, and agnix ships an MCP binary alongside its CLI and language server. The MCP surface is a delivery mechanism, not the product.

Jeff Yaw, Yaw Labs. Follow along at tokenlimit.news for weekly notes on AI infrastructure.

Published by Yaw Labs.