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.
https://github.com/user-attachments/assets/ae9a6b72-8bf7-4b73-abe3-7f0f3b483d3b
Watch the 53-second product overview · Quickstart · Documentation
Real core-rule decisions using a masked synthetic credential. Proposed file writes and commands are evaluated as data, never executed.
Install
pipx install agentlint # Python 3.11+; or: uv tool install agentlint
cd your-project
agentlint setup claude # or: codex, cursor, gemini, continue, kimi, groksetup 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 statusCoding 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:
The token prefix is redacted in this example.
[no-secrets] Possible secret token detected (prefix '[redacted]')
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: falseWhen 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 hooksAll 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.
Star history
License
MIT