agentfile-lint
A linter for agent instruction files (AGENTS.md, CLAUDE.md). Rules and limits live in one
TOML file; the runner is a thin Python program that uses only the standard library
(Python 3.11 or newer). A local git hook and CI call the same program with the same config.
Status: version 0.4.0. Every rule except R1 ships at warn; raise a rule to error in your own config once it is clean.
| Rule | Level (default) | What it checks |
|---|---|---|
R1 |
error | byte and line limits chosen by path glob (first match wins) and a character limit per line; optional marker blocks (for example text a tool injects) are not counted |
R2 |
warn | file shape: required section headings in order, optional title, one-line purpose, bullet-only sections |
R3a |
warn | a test name in backticks is defined in a tracked test file |
R3b |
warn | a path in backticks exists (resolved from the file, its ancestors, the root and configured bases; heuristic) |
R3c |
warn | a §N reference matches a numbered heading in the mapped spec document |
R4 |
warn | dates and issue numbers (rule level), narrative words such as "currently" (narrative_level) |
R5 |
warn | identical lines in an ancestor and a descendant file (rule level) or in sibling files (sibling_level) |
R6 |
warn | candidates for constants copied from code (always a warning) |
C1 |
warn | CLAUDE.md is only the line @AGENTS.md (import-only) or absent (forbid) |
allowlist |
error | time-boxed exceptions: expired or no-longer-needed entries fail, entries warn before they expire |
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
Other commands:
agentfile-lint check-pins # 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)
Output is one line per finding: file:line: rule-id: message. Findings about a whole file use
line 0 (printed as :0). Errors go to stderr, warnings to stdout. 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"]
[rules.R1]
level = "error" # error | warn | off
max_line_chars = 500
excluded_blocks = [{ begin = "<!-- BEGIN:x -->", end = "<!-- END:x -->" }]
# First matching glob wins; a file matching no entry has no size limit.
[[rules.R1.limits]]
glob = "AGENTS.md"
max_bytes = 12000
max_lines = 200 # optional; either or both
[[rules.R1.limits]]
glob = "**/AGENTS.md"
max_bytes = 6000
[allowlist]
max_days = 90
[[allowlist.entries]]
rule = "R1"
path = "docs/AGENTS.md"
reason = "split planned in the tracker"
expires = 2026-12-31
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>
Rules above R1 need configuration to be useful (section lists, base directories, 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.
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.4.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.4.0.tar.gz | 46.2 kB | With provenance | Details for agentfile_lint-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentfile_lint-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for agentfile_lint-0.4.0-py3-none-any.whl |
Total release size: 87.4 kB
Release files / agentfile_lint-0.4.0.tar.gz
| Download URL | agentfile_lint-0.4.0.tar.gz |
|---|---|
| Size | 46.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c3fe54ca12764951dc1a3ef17462aab50816db3535dfe44d74086daa72ee5a61
|
|
BLAKE2b-256 checksum How to use checksums |
8c2189bfbb60cc268343b3a56c33409950ca424f3ed37ab0543f496332dffac4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 1, 2026.
Transparency logRelease files / agentfile_lint-0.4.0-py3-none-any.whl
| Download URL | agentfile_lint-0.4.0-py3-none-any.whl |
|---|---|
| Size | 41.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e7c3521851a0010985fff6e6b58046e2e6c36d3ecdeb9be7fc800cc8f5f273af
|
|
BLAKE2b-256 checksum How to use checksums |
5aa51bd366a0684bfa5596ac1206fea864134d814b70002591783ae1f02f1df3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 1, 2026.
Transparency logSecurity for agentfile-lint 0.4.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.4.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 1, 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.