AI agents trust your context files blindly. Stale paths, wrong commands, and wasted tokens are quietly making them worse.
You spent an afternoon writing a detailed CLAUDE.md. File paths, build commands, architecture notes, conventions. You told your agent exactly how to work in your codebase.
Then two months passed. Someone renamed the auth module. The test command changed from pnpm test to pnpm vitest. A file you referenced got deleted in a refactor.
Your context file didn't notice. But your agent still reads it every single session.
When an AI agent gets wrong context, it doesn't throw an error. It just confidently does the wrong thing. It references files that don't exist. It runs commands that fail. It follows conventions you abandoned months ago. And you blame the model, when the real problem is the instructions you gave it.
Context files are load-bearing infrastructure. They shape every decision your agent makes. But unlike code, they have no tests, no linter, and no CI check. They rot silently.
You reference src/auth/middleware.ts but someone moved it to src/middleware/auth.ts two weeks ago. Your agent now thinks the auth middleware is missing and may try to recreate it, or it hallucinates about the old file structure.
Your context says pnpm test but your package.json only has a vitest script. The agent runs the wrong command, gets an error, then spends tokens trying to debug a problem that doesn't exist.
Your CLAUDE.md hasn't been updated in 47 days, but the directories it references have 8 new commits. The agent is operating on an outdated mental model of your project.
Every token in your context file is loaded into every session. A 3,000-token context file costs you 3,000 tokens before the agent even starts working. If half of that content is stale or redundant, you're paying for noise.
Your context file says "We use React with TypeScript" but both are in your package.json. The agent can already see that. You're spending tokens telling it something it already knows.
We built ctxlint to solve this. It's a linter that validates your AI context files against your actual codebase. Run it and it tells you exactly what's wrong:
$ npx @yawlabs/ctxlint
ctxlint v0.2.1
Scanning /Users/you/my-app...
Found 2 context files (1,847 tokens total)
CLAUDE.md (1,203 tokens, 42 lines)
CLAUDE.md
✗ Line 12: src/auth/middleware.ts does not exist
→ Did you mean src/middleware/auth.ts? (renamed 14 days ago)
✗ Line 8: "pnpm test" — script "test" not found in package.json
⚠ Last updated 47 days ago. src/routes/ has 8 commits since.
ℹ Line 3: "Express" is in package.json dependencies — agent can infer this
Summary: 2 errors, 1 warning, 1 info
Token usage: 1,203 tokens per agent session
Estimated waste: ~55 tokens (redundant content)
It checks five things:
| Check | What it catches |
|---|---|
| Broken paths | File references that don't exist, with rename suggestions from git history |
| Wrong commands | npm/pnpm/yarn scripts and Makefile targets that don't match your project |
| Stale context | Context files that haven't been updated since referenced code changed |
| Token waste | How many tokens your context files consume per session |
| Redundancy | Content your agent can already infer from package.json and other project files |
ctxlint scans context files for Claude Code, Cursor, GitHub Copilot, Windsurf, Gemini, Jules, Cline, and any tool that uses convention files like CONVENTIONS.md. If you have context files, ctxlint can lint them.
The --fix flag uses git rename history and fuzzy matching to automatically correct broken paths in your context files:
$ npx @yawlabs/ctxlint --fix
Fixed 2 paths in CLAUDE.md:
src/auth/middleware.ts → src/middleware/auth.ts
lib/utils/helpers.js → src/utils/helpers.ts
Run ctxlint --strict in your CI pipeline and it exits with code 1 on any warning or error. Your context files get the same protection as your code:
# GitHub Actions
- name: Lint AI context files
run: npx @yawlabs/ctxlint --strict
Or set up a pre-commit hook with npx @yawlabs/ctxlint init so stale context never makes it into a commit.
ctxlint ships with a built-in MCP server, so your AI agent can audit its own context files. Add it to Claude Code and the agent can validate paths, check token usage, and run a full audit without leaving the conversation. The MCP server is tested against the mcp-compliance test suite, and you can deploy it as a hosted server on mcp.hosting for teams that want always-on context validation without running a local process.
We lint our code. We lint our configs. We lint our Dockerfiles. But the files that shape every decision our AI agents make? Those just sit there, rotting.
If you use AI coding tools, your context files are some of the highest-leverage files in your repository. Treat them accordingly.
npx @yawlabs/ctxlint
Published by Yaw Labs.
Interested in AI tools and developer workflows? Token Limit News is our weekly newsletter.