AgentLint
Guardrails for AI coding agents. AgentLint checks what your agent is about
to do — every file write, edit and shell command — and stops the dangerous
parts before they happen: hard-coded secrets, force-pushes to main,
destructive commands, edits to CI pipelines, risky cloud operations.
It works with Claude Code, Codex, Cursor, Gemini CLI, Continue, Kimi, Grok, the OpenAI Agents SDK, MCP hosts and your own tools. It runs locally, and nothing leaves your machine unless you opt in.
Install
pipx install agentlint # Python 3.11+; or: uv tool install agentlint
cd your-project
agentlint setup claude # or: codex, cursor, gemini, continue, kimi, grok
setup adds AgentLint hooks to the agent's settings and writes an
agentlint.yml with packs detected from your project. Restart the agent, make
any tool call, and check that it's working:
agentlint status
Coding agents (configured -> enabled -> observed):
✓ claude (detected) configured: installed (project: …/.claude/settings.json) [PreToolUse, PostToolUse, …] | observed: 4s ago (PreToolUse, this project)
Full walkthrough: Quickstart.
What a block looks like
When an agent tries to write a live API key into config.py, the write never
happens. The agent is told why and what to do instead:
[no-secrets] Possible secret token detected (prefix 'sk_live_')
File: /path/to/project/config.py
Operation: Write
Policy: built-in universal pack; built-in defaults (no policy file)
-> Use environment variables instead of hard-coded secrets.
Findings come in three levels:
- ERROR blocks the action;
- WARNING is passed to the agent as advice;
- INFO appears in the end-of-session report.
What it checks
77 rules in 8 packs. universal and quality are always on; language packs
turn on when AgentLint detects them; security and autopilot are opt-in.
| Pack | Rules | Examples |
|---|---|---|
| universal | 24 | secrets, .env writes, force-push, destructive commands, CI/CD edits, package publishing, test weakening |
| quality | 7 | oversized diffs, removed error handling, dead imports, commit message format |
| python | 6 | SQL built with f-strings, unsafe shell calls, bare except, risky migrations |
| frontend | 8 | missing alt text and labels, focus styles, touch targets |
| react | 3 | unhandled loading/error states, empty states |
| seo | 4 | page metadata, Open Graph, semantic HTML |
| security | 7 | file writes and data exfiltration through the shell |
| autopilot | 18 | production targets, cloud deletions, IAM/firewall changes, terraform apply without a plan (experimental) |
Every rule and option: Rules.
Configure
# agentlint.yml
packs: [python, security] # added to universal + quality
rules:
max-file-size:
limit: 400
no-todo-left:
enabled: false
When a rule gets in the way, use the narrowest fix:
| Situation | Do this |
|---|---|
| The rule doesn't fit this project | enabled: false in agentlint.yml |
| The rule is wrong for some files | allow_paths, or # agentlint:ignore <rule> reason="..." |
| One reviewed command needs to run | an exception (up to 7 days) |
| You approve a kind of action, for now | agentlint approve grant <class> --reason "..." (approvals) |
Shared policies for many repositories, monorepos and required rules: Configuration.
Day-to-day commands
agentlint status # is it running? which policy applies? (--json)
agentlint doctor # find misconfiguration (read-only; --fix to repair)
agentlint check-patch x.patch # preview a Codex patch against the same checks
agentlint evidence # latest test / review / deploy evidence for this repo
agentlint ci --diff origin/main...HEAD # same checks in CI
agentlint uninstall claude # remove the hooks
All commands: CLI reference.
More
- Agent setup guides — one page per agent
- CI · MCP server · Diagnostics
- Custom rules — write your own in a few lines of Python
- AgentChute — optional cloud: threat feeds, team policy, dashboard
- Claude Code marketplace plugin
FAQ
Will it slow my agent down? Each check runs locally in a short-lived process with no network calls on the hook path.
Is my code sent anywhere? No. The optional AgentChute integration sends only redacted event summaries — never file contents, paths, full commands or prompts — and only after you opt in. See what is sent.
Is this a sandbox? No. AgentLint inspects tool calls with rules and heuristics. It catches common mistakes and risky patterns, but a determined process can get around it. Use it alongside code review, CI and least-privilege credentials.
A rule fires repeatedly on something legitimate. Please open an issue with the command or diff. Meanwhile, the circuit breaker gradually downgrades a repeatedly firing rule so it can't stall a session (except security-critical and required rules).
Contributing
See CONTRIBUTING.md. Security reports: SECURITY.md.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for agentlint 2.9.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 | |
|---|---|---|---|
| agentlint-2.9.0.tar.gz | 554.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agentlint-2.9.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 845.8 kB
Release files / agentlint-2.9.0.tar.gz
| Download URL | agentlint-2.9.0.tar.gz |
|---|---|
| Size | 554.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3a538fea18aa9cc8a984d5c705f3cc936e192512a82c1ade67acc12ba693f9c4
|
|
BLAKE2b-256 checksum How to use checksums |
78cc117088d9f164959486d6387b4b08d48e1a65b3394dc4ebcb340bf225c5bf
|
| 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 Oct 8, 2026.
Transparency logRelease files / agentlint-2.9.0-py3-none-any.whl
| Download URL | agentlint-2.9.0-py3-none-any.whl |
|---|---|
| Size | 290.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2d3e1598f7fef96ae24b8a4c8b1c36aa28054e48c741caa26676096a0724a98c
|
|
BLAKE2b-256 checksum How to use checksums |
b57b127fc643dccb56d04346adc45830cc5393f6a336a7a3b2b25223d7ed4731
|
| 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 Oct 8, 2026.
Transparency log
