Metadata-Version: 2.5
Name: agentlint
Version: 2.12.0
Summary: Real-time quality guardrails for AI coding agents
Project-URL: Homepage, https://github.com/mauhpr/agentlint
Project-URL: Repository, https://github.com/mauhpr/agentlint
Project-URL: Issues, https://github.com/mauhpr/agentlint/issues
Project-URL: Changelog, https://github.com/mauhpr/agentlint/blob/main/CHANGELOG.md
Project-URL: Documentation, https://mauhpr.github.io/agentlint/
Author: mauhpr
License-Expression: MIT
License-File: LICENSE
Keywords: agent-guardrails,agentic,ai-agents,ai-code-review,ai-linting,ai-safety,claude-code,code-quality,code-review,codex,continue,cursor,gemini,grok,guardrails,hooks,kimi,linting,mcp,pre-commit,tool-use
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: fastmcp>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: fastmcp>=3.0; extra == 'mcp'
Description-Content-Type: text/markdown

# AgentLint

**Catch risky actions while your coding agent works.**

AgentLint checks proposed file changes and shell commands locally. It blocks detected secret writes and plain force-pushes to `main` or `master`, warns about risky operations, and gives your agent feedback it can act on.

[![PyPI](https://img.shields.io/pypi/v/agentlint)](https://pypi.org/project/agentlint/)
[![CI](https://github.com/mauhpr/agentlint/actions/workflows/ci.yml/badge.svg)](https://github.com/mauhpr/agentlint/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mauhpr/agentlint/branch/main/graph/badge.svg)](https://codecov.io/gh/mauhpr/agentlint)
[![Downloads](https://api.pepy.tech/badge/agentlint)](https://pepy.tech/projects/agentlint)
[![GitHub stars](https://img.shields.io/github/stars/mauhpr/agentlint)](https://github.com/mauhpr/agentlint/stargazers)
[![Python](https://img.shields.io/pypi/pyversions/agentlint)](https://pypi.org/project/agentlint/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Quickstart](https://mauhpr.github.io/agentlint/quickstart/) · [Documentation](https://mauhpr.github.io/agentlint/) · [Integration coverage](https://mauhpr.github.io/agentlint/coverage/) · [Rules](https://mauhpr.github.io/agentlint/rules/)

![A proposed credential write is blocked, the agent receives a correction, and a revised proposal is checked again.](https://raw.githubusercontent.com/mauhpr/agentlint/main/docs/assets/correction-loop.svg)

*Illustration with a supported pre-tool hook and standard policy. AgentLint evaluates the revised proposal again; it does not rewrite your code itself.*

<a id="what-a-block-looks-like"></a>

## See the difference

A coding agent proposes putting a credential in `config.py`. The `no-secrets` rule denies the write and returns a reason:

```text
[no-secrets] Secret assignment detected: api_key=...
  -> Use environment variables instead of hard-coded secrets.
```

The agent can replace the literal with an environment-variable lookup:

```python
import os

api_key = os.environ["SERVICE_API_KEY"]
```

The credential finding is resolved. The revised action is checked against the active policy, and any other findings still apply.

https://github.com/user-attachments/assets/ae9a6b72-8bf7-4b73-abe3-7f0f3b483d3b

[Watch the 53-second product overview](https://mauhpr.github.io/agentlint/media/agentlint-demo.mp4). The demonstration evaluates synthetic proposed actions as data; it does not execute dangerous commands.

<a id="install"></a>

## Get started

Requires Python 3.11+ and [pipx](https://pipx.pypa.io/stable/installation/) or [uv](https://docs.astral.sh/uv/getting-started/installation/).

```bash
uv tool install agentlint
cd your-project
agentlint setup claude
```

Use your agent's name for the last command:

| Agent | Setup | Activate |
|-------|-------|----------|
| [Claude Code](https://mauhpr.github.io/agentlint/agents/claude/) | `agentlint setup claude` | Restart Claude Code |
| [Codex](https://mauhpr.github.io/agentlint/agents/codex/) | `agentlint setup codex` | Restart, then review and trust the hooks in `/hooks` |
| [Cursor](https://mauhpr.github.io/agentlint/agents/cursor/) | `agentlint setup cursor` | Reload the Cursor window |
| [Gemini CLI](https://mauhpr.github.io/agentlint/agents/gemini/) | `agentlint setup gemini` | Start a new session |
| [Continue](https://mauhpr.github.io/agentlint/agents/continue/) · [Kimi](https://mauhpr.github.io/agentlint/agents/kimi/) · [Grok](https://mauhpr.github.io/agentlint/agents/grok/) | `agentlint setup continue`, `kimi`, or `grok` | Follow the linked agent guide |

Prefer pipx? Use `pipx install agentlint` instead. Setup adds hooks to your agent's settings and creates `agentlint.yml` if it does not exist, using packs detected from the project.

Make one tool call in your agent, then run:

```bash
agentlint status
```

Look for a recent **observed** hook call from this project. A configuration file alone does not prove the hooks are running. If nothing is observed, run `agentlint doctor` and follow [troubleshooting](https://mauhpr.github.io/agentlint/diagnostics/).

The [five-minute quickstart](https://mauhpr.github.io/agentlint/quickstart/) completes the first check and correction. Claude Code users can alternatively install the [marketplace plugin](https://github.com/mauhpr/agentlint-plugin); use the plugin or native setup to avoid duplicate hooks.

<a id="what-it-checks"></a>

## What blocks, what warns

With standard severity and the relevant pre-tool hook:

| Outcome | Examples | Requirement |
|---------|----------|-------------|
| **Block** | Detected secret writes, `.env` writes, plain `--force`/`-f` pushes to `main`/`master`, CI pipeline edits, package publishing | Core rules, subject to configuration and each rule's scope |
| **Warn** | Many destructive commands, direct pushes to `main`, protected-branch `--force-with-lease`, test weakening, removed error handling | Core rules; some catastrophic destructive patterns block instead |
| **Check your stack** | SQL interpolation, unsafe Python shell calls, frontend accessibility, React loading states | Detected language/framework packs |
| **Opt in** | Shell file-write restrictions and network exfiltration checks | `security` pack |
| **Opt in, experimental** | Production targets, cloud deletions, infrastructure mutations | `autopilot` pack |

Some rules run after a tool call or at session end and cannot prevent an action that has already happened. Severity settings, approvals, exemptions, and the circuit breaker affect decisions. The [rule reference](https://mauhpr.github.io/agentlint/rules/) documents the exact behavior.

**Integration matters.** Native hooks inspect the tools their host reports. The [OpenAI Agents SDK adapter](https://mauhpr.github.io/agentlint/agents/openai-agents/) must be attached to supported tools. The [MCP server](https://mauhpr.github.io/agentlint/agents/mcp-hosts/) provides on-demand checks and is advisory. See [coverage and limitations](https://mauhpr.github.io/agentlint/coverage/) before relying on an integration.

AgentLint includes 77 built-in rules in 8 packs:

| 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 | shell file-write restrictions and network exfiltration patterns *(opt-in)* |
| autopilot | 18 | production targets, cloud deletions, IAM/firewall changes, infrastructure previews *(opt-in, experimental)* |

The [rule catalogue](https://mauhpr.github.io/agentlint/rules/) lists each rule's event, severity, and configuration.

<a id="configure"></a>

## Make it fit your project

```yaml
# agentlint.yml
packs: [python, security]  # explicit selection; core packs are also loaded
rules:
  max-file-size:
    limit: 400
  no-todo-left:
    enabled: false
```

An explicit `packs` list replaces stack detection. The `universal` and `quality` packs are included unless deliberately excluded. Start with detected defaults and add stricter packs when you need them.

| You want to… | Start here |
|--------------|------------|
| Protect a shared branch while keeping normal Git work moving | [Protect main](https://mauhpr.github.io/agentlint/guides/protect-main/) |
| Fix a legitimate action that keeps getting flagged | [Handle a false positive](https://mauhpr.github.io/agentlint/guides/fix-a-false-positive/) |
| Run Ruff, ESLint, or a formatter after agent edits | [Connect your linters](https://mauhpr.github.io/agentlint/guides/run-linters/) |
| Apply a shared policy across repositories | [Share required rules](https://mauhpr.github.io/agentlint/guides/shared-policy/) |
| Enforce a convention specific to your codebase | [Write a custom rule](https://mauhpr.github.io/agentlint/custom-rules/) |

<a id="day-to-day-commands"></a>
<a id="more"></a>

## Use the same checks beyond the agent

```bash
agentlint check-patch change.patch       # preview a Codex patch without applying it
agentlint ci --diff origin/main...HEAD   # check the pull request's file changes
agentlint evidence                      # inspect verification receipts
agentlint uninstall claude              # remove Claude Code's native hooks
```

CI checks file changes; it does not reconstruct or audit every shell command the agent ran. [CI setup](https://mauhpr.github.io/agentlint/ci/) · [CLI reference](https://mauhpr.github.io/agentlint/cli/)

<a id="faq"></a>

## Local by default

Hook checks run locally. You do not need an account or a network connection for the offline rules. Optional [AgentChute](https://mauhpr.github.io/agentlint/agentchute/) adds threat feeds, team policy, and visibility; feed-backed rules need that data. Cloud event delivery is opt-in and sends redacted summaries rather than file contents or full commands.

AgentLint uses rules and heuristics. It can miss risky behavior, flag legitimate work, and be bypassed by a process with broad access. Keep code review, tests, CI, and least-privilege credentials in place. [Security model](https://mauhpr.github.io/agentlint/coverage/#security-boundary) · [Report a vulnerability](https://github.com/mauhpr/agentlint/security/advisories/new)

<a id="contributing"></a>

## Contribute

Start with [CONTRIBUTING.md](https://github.com/mauhpr/agentlint/blob/main/CONTRIBUTING.md). A regression case for a false positive or a missed detection is a useful first contribution. AgentLint includes 77 built-in rules in 8 packs; the [catalogue](https://mauhpr.github.io/agentlint/rules/) is generated in part from the code and checked in CI.

<a id="license"></a>

[Changelog](https://github.com/mauhpr/agentlint/blob/main/CHANGELOG.md) · [Issues](https://github.com/mauhpr/agentlint/issues) · [Security policy](https://github.com/mauhpr/agentlint/blob/main/SECURITY.md) · [MIT license](https://github.com/mauhpr/agentlint/blob/main/LICENSE)

## Star history

[![AgentLint star history](https://api.star-history.com/svg?repos=mauhpr/agentlint&type=Date)](https://www.star-history.com/#mauhpr/agentlint&Date)
