Skip to main content

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 equal python3 -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.py recomputes 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)

Source distribution for agentfile-lint 0.4.0
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)

Table of built distributions (wheels) for agentfile-lint 0.4.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page