Lint the files your coding agents read.
agentlint checks CLAUDE.md, AGENTS.md, Cursor rules, Claude Code settings and MCP config. Every finding has a line number, a fix, and the official doc that backs it.
npx @devtaeyeong/agentlint
- 12 rules, each linked to its source doc.
- Pretty, JSON and SARIF output.
- MIT licensed.
$ npx @devtaeyeong/agentlint .claude/settings.json 3:35 error allow "Bash(git push --force *)" allows force-pushing. Allow specific commands instead, or move it to "ask". dangerous-allow https://code.claude.com/docs/en/permissions#wildcard-patterns .mcp.json 6:34 error Server "linear" env.LINEAR_API_KEY holds a literal secret. Reference an environment variable instead, e.g. "${VAR}", and rotate the exposed value. mcp-hardcoded-secret https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json CLAUDE.md 5:1 warn Mutually exclusive choices (npm vs pnpm): "- Always use pnpm for scripts." conflicts with "- Use npm for scripts." (AGENTS.md:3). If two instructions contradict, the agent may pick one arbitrarily. conflicting-rules https://code.claude.com/docs/en/memory#write-effective-instructions 8 problem(s) in 5 file(s): 4 error, 4 warning, 0 info 1 fixable with --fix
When agentlint flags something, it tells you the line, the fix, and the doc that says so.
- One pass over Claude Code, Cursor, AGENTS.md and MCP config.
- Runs in CI with exit codes and SARIF, and leaves one comment on the PR.
- Catches the config that breaks quietly: dead imports, conflicting rules,
Bash(*), keys in.mcp.json.
Rules
- file-too-longCLAUDE.md over 200 lines, or a Cursor rule or SKILL.md over 500 lines.
- conflicting-rulesTwo instructions contradict each other (within or across instruction files).
- duplicate-contentThe same instruction line appears more than once, costing context on every load.
- broken-importAn @path import in CLAUDE.md/AGENTS.md points to a missing file, or nests deeper than four hops.
- settings-invalid-jsonClaude Code settings file is not strict JSON (comments and trailing commas are errors).
- missing-secret-denyProject Claude Code settings do not deny reading .env files.
- dangerous-allowpermissions.allow auto-approves broad or destructive Bash commands.
- bypass-permissions-modeProject settings set defaultMode to bypassPermissions.
- unsafe-hookA command hook runs something unsafe; hooks execute with your full user permissions.
- mdc-frontmatterCursor .mdc rule has missing or invalid frontmatter (description, globs, alwaysApply).
- md-in-cursor-rulesA plain .md file in .cursor/rules is ignored by Cursor; rules must use .mdc.
- legacy-cursorrules.cursorrules is legacy and will be deprecated.
FAQ
Which files does it check?
CLAUDE.md, CLAUDE.local.md, .claude/rules, settings, skills, subagents, .mcp.json, Cursor .mdc/.md rules, .cursorrules, .cursor/mcp.json and AGENTS.md. It skips node_modules, .git, dist, build, coverage, .next and vendor.
Why should I trust a finding?
Each rule links to the vendor doc it enforces. If the docs don't say it, agentlint doesn't flag it.
Does --fix change my instructions?
No. It only adds .env deny rules and fixes quoted alwaysApply values.
Does it work on private repos?
Yes. SARIF upload needs GitHub code scanning (Advanced Security); if it fails, the action notes it in the PR comment. Set upload-sarif: "false" to skip.
How is it different from /doctor prompt-audit?
That runs inside a Claude Code session and proposes edits. agentlint runs in CI and gives the same result every run. You can run both.
Will it catch every conflict?
No. conflicting-rules is a heuristic and misses some.
What do I need to run it?
Node.js 20.12 or later.