agentfile-lint
A linter for agent instruction files (AGENTS.md, CLAUDE.md) that a team runs the same way in every
repository: rules are data in one TOML file, debt exceptions expire while permanent path scopes live in
the config with a required reason, and the runner is plain Python with no
dependencies, so the git hook, CI and a vendored copy give the same answer. It checks AGENTS.md
and CLAUDE.md today; SKILL.md, hooks and MCP config are next if it proves useful.
uvx agentfile-lint # in any git repository; no config needed
With no config it runs only checks whose findings are facts. From a demo repository:
$ uvx agentfile-lint
AGENTS.md: warning: R1b: file is 211 lines, limit 200
AGENTS.md:9: warning: R3a: test `test_login_redirects` is not defined in any searched test file
services/api/AGENTS.md: error: R1c: file and its ancestors (AGENTS.md) total 34618 bytes, limit 32768
services/api/AGENTS.md:3: warning: R5a: line repeats AGENTS.md:8 ('Never edit generated files under `gen/`; change the schem...'); keep it in the ancestor only
$ echo $?
1
Codex stops reading AGENTS.md files on a path once they total 32 KiB (its default), so the total for
services/api/AGENTS.md is an error; the others are warnings. extends = ["preset:strict"] in
.agentfile-lint.toml adds the heuristic rules, which guess and are wrong more often (rates in
docs/rules.md). Same repository:
$ printf 'extends = ["preset:strict"]\n' > .agentfile-lint.toml
$ uvx agentfile-lint
AGENTS.md: warning: R1b: file is 211 lines, limit 200
AGENTS.md:9: warning: R3a: test `test_login_redirects` is not defined in any searched test file
CLAUDE.md: warning: C1: CLAUDE.md must contain only the line '@AGENTS.md'
services/api/AGENTS.md: error: R1c: file and its ancestors (AGENTS.md) total 34618 bytes, limit 32768
services/api/AGENTS.md:3: warning: R5a: line repeats AGENTS.md:8 ('Never edit generated files under `gen/`; change the schem...'); keep it in the ancestor only
services/api/AGENTS.md:4: warning: R3b: path `src/legacy/router.py` not found from this file's directory, its ancestors, the repo root or base_dirs
services/api/AGENTS.md:5: warning: R4b: narrative word 'currently'; describe the current rule, not its history
services/api/AGENTS.md:5: warning: R6: possible copied constant '`MAX_RETRIES = 5`'; point to the code instead of repeating the value
| Rule | Default | preset:strict |
What it checks |
|---|---|---|---|
R1a |
error | error | bytes per file: your own limits by glob (none by default) |
R1b |
warn | warn | lines per file: AGENTS.md or CLAUDE.md over 200 lines; your own limits by glob |
R1c |
error | error | AGENTS.md files on one path over 32 KiB in total |
R1d |
off | off | characters per line (max_chars) |
R2 |
warn | warn | file shape: required section headings in order, optional title, one-line purpose, bullet-only sections (needs config) |
R3a |
warn | warn | a test name in backticks is defined in a tracked test file |
R3b |
off | warn | a path in backticks exists (heuristic) |
R3c |
warn | warn | a §N reference matches a numbered heading in the mapped spec document (needs config) |
R4a |
off | warn | dates and issue numbers (heuristic) |
R4b |
off | warn | narrative words such as "currently" (heuristic) |
R5a |
warn | warn | identical lines in a same-name file of an ancestor directory; strict: any file in an ancestor or the same directory |
R5b |
off | warn | identical lines in sibling files |
R6 |
off | warn | candidates for constants copied from code (heuristic, always a warning) |
C1 |
off | warn | CLAUDE.md is only the line @AGENTS.md (import-only) or absent (forbid) |
allowlist |
error | error | exceptions: expired, no-longer-needed or miscounted (count above or below the findings) allowlist entries fail, entries warn before they expire; an override glob that matches no file warns |
Every rule except R1a and R1c ships at warn or off; raise a rule to error in your own config once it is
clean. Why each rule exists, where its default comes from and its measured false-positive rate:
docs/rules.md. What it found on 22 popular public repositories with no config, and
how that changed from 0.4.0: docs/field-report.md.
Other instruction files
The default checks AGENTS.md and CLAUDE.md only. To add others, list them in [discover] globs:
[discover]
globs = ["AGENTS.md", "**/AGENTS.md", "CLAUDE.md", "**/CLAUDE.md",
"GEMINI.md", "**/GEMINI.md", ".github/copilot-instructions.md"]
- The list replaces the default list, so repeat the four
AGENTS.md/CLAUDE.mdglobs. - With
preset:strict, R5a compares files of different names too, so aGEMINI.mdthat copies theAGENTS.mdnext to it is reported line by line. The default compares only same-name files.
Compared with similar tools
From each tool's own documentation, checked 2026-11-03; nothing here was installed or run. "Not documented" means the documentation does not say, not that the feature is missing.
| agentfile-lint | agnix | ctxlint | agentlinter | |
|---|---|---|---|---|
| Runs on | Python 3.11+, standard library only | Rust binary (npm, brew, pip, cargo) | Node (npx), no runtime dependencies |
Node 18+ (npx) |
| Files | AGENTS.md, CLAUDE.md; others by glob |
CLAUDE.md, AGENTS.md, SKILL.md, hooks, MCP, Cursor, Copilot, more |
context files of 16 tools, MCP config | CLAUDE.md, AGENTS.md, SKILL.md, Cursor, Copilot, more |
| Shared config | extends presets and files |
extend base files |
not documented | extends of the built-in preset |
| Exceptions | allowlist entries need a reason and an expiry date, expired or unneeded entries fail; path overrides only lower a level and need a reason | disabled rules, per-file overrides, inline comments | ignored rules with an optional reason; unused ones reported | ignored paths |
| Vendored copy | reproducible directory with a hash check | not documented | not documented | not documented |
| References checked | test names, §N spec sections; paths with preset:strict |
import paths, commands, referenced files | paths, commands (against package.json, Makefile) |
file references, imports |
| Duplicates between files | identical lines in a file and its ancestors | not documented | duplicate content across files | duplicate content; across files not documented |
| Auto-fix | no | yes | broken paths | yes |
| Editor | no | LSP, IDE plugins | LSP | no |
| Output | file:line: severity: rule-id: message, JSON, GitHub; exit 0/1/2 |
GitHub, JSON, SARIF | text, JSON, SARIF; exit 0/1/2 | GitHub; 0-100 score |
Choose agnix for breadth (many file types, IDE plugins, auto-fix). Choose agentfile-lint to run one small, pinned set of rules across many repositories: debt exceptions expire and permanent ones are written down with a reason, the checker can be vendored and verified, and the output and exit codes are a tested contract.
Usage
python3 -m agentfile_lint # from a git repository; analyzes tracked files only
agentfile-lint --list-rules # rules and their effective levels
agentfile-lint --today 2026-01-31 # replace the current date (reproducible runs)
agentfile-lint --config path.toml # explicit config instead of .agentfile-lint.toml
agentfile-lint --warn-as-error
agentfile-lint --format json # or github (workflow commands); default text
Other commands:
agentfile-lint check-pins # (experimental) every reference to this tool pins the same full commit SHA
agentfile-lint config --format json # the effective merged configuration, sorted keys
agentfile-lint vendor --to DIR # a pinned, self-contained copy (see below)
Experimental commands may change their output and options in any minor release; everything else
follows docs/versioning.md.
Findings go to stdout, one line each: file:line: severity: rule-id: message, where severity is
error or warning; a finding about a whole file has no line: file: severity: rule-id: message.
--format json prints one document, {"version": 1, "findings": [...]}, each finding with file,
line (null for a whole file), level, rule and message; --format github prints GitHub
workflow commands. Usage and configuration problems go to stderr. Exit codes: 0 no errors, 1 at
least one error, 2 usage or configuration problem.
Files given on the command line are ignored; the full tracked set is always analyzed
(cross-file checks and allowlist checks need it). Untracked local instruction
files (*.local.md) are never analyzed.
Configuration
.agentfile-lint.toml at the repository root extends the shipped preset. Unknown keys fail.
extends = ["preset:default"] # default; other entries are paths relative to this file
[discover]
globs = ["AGENTS.md", "**/AGENTS.md"]
[shared.size] # parameters R1a, R1b and R1d share
excluded_blocks = [{ begin = "<!-- BEGIN:x -->", end = "<!-- END:x -->" }]
[rules.R1d]
level = "error" # error | warn | off; each rule id has one level
max_chars = 500 # required unless R1d is off
# First matching glob wins; a file matching no entry has no limit.
[[rules.R1a.limits]]
glob = "AGENTS.md"
max_bytes = 12000
[[rules.R1a.limits]]
glob = "**/AGENTS.md"
max_bytes = 6000
[allowlist]
max_days = 90
[[allowlist.entries]]
rule = "R1a"
path = "docs/AGENTS.md"
count = 1 # findings of R1a in that file; more or fewer fail
reason = "split planned in the tracker"
expires = 2026-12-31
# Permanent path scope: translated copies duplicate the root file on purpose.
[[overrides]]
paths = ["docs/*/AGENTS.md"]
rules = { ancestor-duplicates = "off" } # rule id or alias -> "warn" or "off"; never raises a level
reason = "translations of the root AGENTS.md"
The allowlist is for debt with an end date; [[overrides]] is for paths that are meant to differ.
An override only lowers a rule's level (the lowest of the rule and every matching override wins), and
entries from extends are added to the repository's own. A glob in your config that matches no
instruction file is a warning.
Install and wire up
pre-commit:
- repo: https://github.com/Will413028/agentfile-lint
rev: <tag or full commit SHA>
hooks:
- id: agentfile-lint
Run on every commit and push: rules R3a, R3b and R3c read test files, source and docs, and cross-file
rules read the whole tracked set, so do not filter the hook, lefthook entry or workflow by instruction
files (no files:, glob: or paths: filters). The pre-commit hook sets always_run: true.
lefthook (no path filter):
pre-commit:
commands:
agentfile-lint:
run: python3 -m agentfile_lint
GitHub Actions (pin to a full commit SHA; no paths: filter, plus a weekly run so allowlist expiry
warnings appear even when nobody commits):
on:
push:
pull_request:
schedule:
- cron: "0 6 * * 1" # weekly
# steps:
- uses: actions/checkout@<sha>
- uses: Will413028/agentfile-lint@<sha>
The action runs with --format github, so findings appear as annotations on the pull request. GitHub
shows at most 10 errors and 10 warnings per step; the others stay in the log with their file and line.
R2 and R3c need configuration to check anything (section lists, spec mappings); the preset
documents every key. A rule at error can still emit some findings as warnings.
The review criteria for what no program can decide are in rubric.md, with a pull request snippet in
docs/pr-template-snippet.md; the release and upgrade process is in docs/versioning.md.
Development: make check runs the unit tests (needs Python 3.11+, override with PYTHON=...).
Design notes are in docs/design.md, decisions in docs/adr/.
Vendored copy
For environments that cannot install from git, agentfile-lint vendor --to <dir> writes one
self-contained directory: the runner package with the default preset, an entry script
(agentfile-lint.py), verify.py and a README.md that records the upstream tag, the upstream
commit and a SHA-256 for every file. Options: --ref-tag / --ref-commit (default: the exact tag
and HEAD of the source checkout, else untagged), --force (replace a non-empty target).
- Run it from the repository root:
python3 <dir>/agentfile-lint.py(Python >= 3.11, standard library only, no network). Its output and exit codes equalpython3 -m agentfile_lint. - The output is reproducible: same source and same two upstream values give a byte-identical tree (sorted order, fixed newlines, no timestamps, no machine paths or user names).
python3 <dir>/verify.pyrecomputes the hashes and fails (exit 1, naming the file) on a modified, missing or unlisted file.vendorandverify.pyare part of the compatibility contract (docs/versioning.md).
Known limitation: verification only detects accidental modification. A deliberate change can edit the files and the manifest together, so it is not tamper-proof. The real gate is review of the diff of the pull request that upgrades the vendored copy.
License
MIT, see LICENSE.
Metadata
Release files for agentfile-lint 0.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentfile_lint-0.7.0.tar.gz | 75.4 kB | With provenance | Details for agentfile_lint-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentfile_lint-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for agentfile_lint-0.7.0-py3-none-any.whl |
Total release size: 130.2 kB
Release files / agentfile_lint-0.7.0.tar.gz
| Download URL | agentfile_lint-0.7.0.tar.gz |
|---|---|
| Size | 75.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4b071e9190d1b02c8fade38b1ddb52d15ee1ee21745850c22f3cdbb59d35388c
|
|
BLAKE2b-256 checksum How to use checksums |
c6141b2025335feb316e5ba83ff6caf941456801b719c26e414327ebddc9dad1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / agentfile_lint-0.7.0-py3-none-any.whl
| Download URL | agentfile_lint-0.7.0-py3-none-any.whl |
|---|---|
| Size | 54.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1f50edd6e24d0e1c3803e24bd761f5b487d0137576c266c069fc3350307ebdd9
|
|
BLAKE2b-256 checksum How to use checksums |
72409b15be6e085f542a8ebb6a8172fda4cc121e377458136487d1b4280de239
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for agentfile-lint 0.7.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agentfile_lint-0.7.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.