agentslint

A tool to keep AGENTS.md instructions honest as the repository changes.

agentslint is a static referential-integrity checker for AI agent instruction files. It finds stale file paths, broken internal links, missing command targets, and undeclared development tools before an agent follows outdated guidance.

services/api/AGENTS.md:18: error[path-exists]: path does not exist: src/legacy.py
services/web/AGENTS.md:27: error[npm-script]: npm script does not exist in services/web/package.json: verify
AGENTS.md:42: warning[scope-ambiguous]: make command has multiple applicable Makefiles: services/api/Makefile, services/web/Makefile

agentslint: checked 3 instruction files; 2 errors, 1 warning

The validator reads repository content but never executes commands from AGENTS.md, imports application code, installs project dependencies, or accesses external URLs.

Why agentslint?

Agent instructions are operational documentation. A renamed test, moved service, removed script, or retired formatter can silently turn correct guidance into a bad plan. Ordinary code tests rarely catch that drift because the Markdown itself did not change.

agentslint check . scans every tracked root and nested AGENTS.md, even when those files are unchanged. It checks the current working tree against the repository structure and manifests that the instructions describe.

Use it to:

• Catch references to files and directories that were moved or deleted.
• Verify internal Markdown links, heading anchors, globs, and path templates.
• Check Make targets, npm scripts, Python modules, pytest nodes, Go tests, and dbt selectors without running them.
• Detect development tools still named in instructions after their declarations were removed.
• Surface ambiguous project scopes before an agent chooses the wrong service.
• Add a focused, read-only integrity check to local development, pre-commit, and CI.

Install

agentslint requires Python 3.11 or newer.

Run it without a persistent installation:

uvx agentslint check .

Or install it permanently onto your machine with uv:

uv tool install agentslint

Then run:

$ agentslint check .
agentslint: checked 1 instruction file; no issues found

Quick start

No configuration is required for conventional repositories. From anywhere inside a Git repository:

agentslint check .

agentslint discovers tracked AGENTS.md files recursively and uses the Git index as its canonical repository inventory. Staged additions count; deleted and untracked references do not count unless an untracked root is explicitly configured. Outside a Git worktree, agentslint falls back to a filesystem walk with standard dependency and VCS directories excluded.

To check one subtree or instruction file while retaining repository-wide resolution:

agentslint check services/frontend
agentslint check services/frontend/AGENTS.md

Use --strict when warnings about ambiguity or unsupported syntax should also fail:

agentslint check . --strict

What it validates

Dynamic shell expressions and selectors that cannot be proven statically produce warnings instead of being evaluated. The tool favors an explicit ambiguity diagnostic over silently selecting one plausible project.

Exit codes and output

Text output is the default and ends with the number of instruction files checked plus error and warning totals. GitHub annotations and versioned JSON are also available:

agentslint check . --format text
agentslint check . --format github
agentslint check . --format json

Configuration

See Configuration.

GitHub Actions

See GitHub Actions.

Safety and boundaries

agentslint treats repository content as untrusted input:

• Documented shell commands, Makefiles, tests, dbt projects, and application modules are never executed or imported.
• Validation is local and read-only apart from normal tool caches and report output.
• External links are not fetched.
• Paths are constrained to the repository.
• Input files are size-bounded and parsed with data-only readers.

It checks whether instructions refer to real repository objects. It does not judge whether the advice is strategically correct, prove that a command succeeds at runtime, rewrite documentation, or replace language-specific tests and linters.