agentlint
agentlint is a Python CLI that lints AI coding-agent git diffs for common risky patterns using static analysis only (no LLM calls).
Install
pip install ai-agentlint
For local development:
pip install -e ".[dev]"
Quick Start
Basic check against last commit:
agentlint check
Check staged changes:
agentlint check --staged
Check a commit range:
agentlint check HEAD~3..HEAD
Pipe a diff through stdin:
git diff | agentlint check --stdin
Provide task context for scope-aware checks:
agentlint check --task "only update parser error handling"
JSON output for automation:
agentlint check --format json
Markdown output for PR comments:
agentlint check --format markdown
Available report formats: text (default), json, and markdown.
Checks
scope_drift: Warns when changed files appear unrelated to--task. Example: task is "parser bugfix" but diff editsinfra/main.tf.secret_leak: Errors on likely credential leaks (AWS/GitHub tokens, passwords, private keys, DB URLs). Example: added linepassword = "supersecret123".test_regression: Warns when test lines are deleted without replacement or tests are changed off-task. Example: deletetests/test_api.pyassertions and add no test updates.config_vandalism: Warns for CI/infra/lock-file edits outside scope. Example: modify.github/workflows/ci.ymlin a docs-only task.dependency_injection: Warns when new dependencies are introduced unexpectedly. Example: addflask==3.0.0torequirements.txtwithout dependency-related task text.todo_bombs: Warns/errors on TODO/FIXME/HACK spikes. Example: adding 4 TODO markers raises an error.mcp_permissions: Errors on dangerous MCP server configuration patterns. Example:.mcp.jsonwith"autoApprove": trueor"autoApprove": ["*"](related to CVE-2026-21852 auto-approve bypass).permission_escalation: Errors on risky patterns (sudo, permissivechmod,eval,exec,shell=True,os.system). Example:subprocess.run(cmd, shell=True).dead_code: Warns on added commented-out code blocks (5+ lines). Example: pasting a large block of# old implementationlines.
Configuration
agentlint discovers .agentlint.toml by walking up from the current directory.
disabled_checks = ["scope_drift"]
[severity]
todo_bombs = "error"
config_vandalism = "info"
[ignore]
secret_leak = ["tests/fixtures/*"]
scope_drift = ["docs/*"]
[secrets]
allowed_patterns = ["^dummy_token_for_tests$"]
CLI config controls:
--config PATH: Load config from explicit file.--no-config: Ignore discovered config files.
GitHub Actions
Use the bundled composite action in this repository to lint PR diffs and post markdown results as a pull request comment.
name: agentlint
on:
pull_request:
permissions:
contents: read
pull-requests: write
jobs:
lint-diff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- run: git fetch origin main --depth=1
- uses: ./
id: agentlint
with:
fail-on-error: true
fail-on-warning: false
format: markdown
comment: true
python-version: "3.12"
- if: always()
run: |
echo "exit-code=${{ steps.agentlint.outputs.exit-code }}"
printf '%s\n' "${{ steps.agentlint.outputs.report }}"
Context File Validation
Beyond linting git diffs, agentlint can validate your context files (AGENTS.md, CLAUDE.md, GEMINI.md) directly for staleness, bloat, and internal conflicts.
agentlint check-context
Or target a specific file:
agentlint check-context CLAUDE.md --format json
Context checks
| ID | Severity | What it catches |
|---|---|---|
CTX001 |
warning | path-rot — file/dir paths mentioned in the context file that no longer exist |
CTX002 |
warning | script-rot — npm run <script> references missing from package.json |
CTX003 |
warning/error | bloat — context files >8k chars (warning) or >15k chars (error); per ETH Zurich ICSE 2026, stale context adds ~20% token overhead |
CTX004 |
info | stale-todos — TODO/FIXME/HACK/XXX markers that may confuse agents |
CTX005 |
warning | year-rot — references to 2023 or earlier may be outdated guidance |
CTX006 |
warning | multi-file-conflict — conflicting test/build commands across multiple context files |
Freshness score
Every run produces a freshness score (0–100). Each finding deducts points:
- error: −15
- warning: −5
- info: −2
A score below 70 suggests the context file needs a cleanup pass.
Works alongside agentlint check
agentlint check lints what agents write (git diffs). agentlint check-context lints what agents read (context files). Together they cover the full agent quality surface.
CI integration
Add a weekly context health check with the bundled GitHub Action:
- uses: mikiships/agentlint@main
with:
mode: context-check
# context-file: AGENTS.md # optional, auto-detected otherwise
See .github/workflows/examples/agentlint-context-check.yml for a full example.
Why agentlint?
- Enforces deterministic, static checks suitable for CI gates.
- Focuses on agent-specific failure patterns in patch output.
- Fast enough to run on every PR and staged commit.
Part of the Agent Toolkit
agentlint is one of three tools for AI coding agent quality:
- coderace — Race coding agents against each other on real tasks. Automated, reproducible, scored comparisons.
- agentmd — Generate and score context files (CLAUDE.md, AGENTS.md, .cursorrules) for AI coding agents.
- agentlint — Lint AI agent git diffs for risky patterns. Static analysis, no LLM required.
Measure (coderace) → Optimize (agentmd) → Guard (agentlint).
Contributing
- Create a branch.
- Add or update checks/tests/docs together.
- Run
pytest -v --cov=agentlint --cov-report=term-missing. - Open a PR with a short rationale and sample diff cases.
License
MIT. See LICENSE.
Metadata
Release files for ai-agentlint 0.4.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_agentlint-0.4.3-py3-none-any.whl | Python 3 | none | any | Details for ai_agentlint-0.4.3-py3-none-any.whl |
Release files / ai_agentlint-0.4.3-py3-none-any.whl
| Download URL | ai_agentlint-0.4.3-py3-none-any.whl |
|---|---|
| Size | 30.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3ec70aec3b1935c118389648a3584c7f13c038b6e61fee26f2957c254e97a802
|
|
BLAKE2b-256 checksum How to use checksums |
fe087df114909144da07e2ce033c8559ebc139505be5aeef1157e52627f2d6ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for ai-agentlint 0.4.3
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.