ailint
Lint AI agent configuration files for structural problems that agents silently ignore.
What it does
- Scans CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .windsurfrules for bloat, vague language, redundancy, dead references, and contradictions.
- Reports problems with file:line:column, severity, rule ID, and suggested fixes.
- Provides
--deepmode for semantic contradiction analysis via the Claude CLI.
Quick start
pip install airulelint
ailint # auto-detects config file in current directory
ailint CLAUDE.md # specify a file
ailint --deep AGENTS.md # add LLM-powered semantic analysis
Example output
$ ailint CLAUDE.md
CLAUDE.md:3:20 warning [R002] Vague phrase 'try to' is hard to enforce.
suggestion: Replace it with a concrete condition, threshold, or required action.
CLAUDE.md:27:1 warning [R005] Possible contradiction in section 'Task Execution': ...
suggestion: Clarify the condition that decides whether action is automatic or requires confirmation.
CLAUDE.md:145:5 error [R004] Referenced path does not exist: rules/deploy-sop.md
suggestion: Fix the path, create the referenced file, or remove the stale reference.
✖ 3 problems (1 error, 2 warnings)
Clean file:
$ ailint CLAUDE.md
✔ No problems found
Rules
| ID | Name | Default Severity | What it catches |
|---|---|---|---|
| R001 | bloat | warning / error | File >500 lines (warn) or >1000 (error). Sections >100 lines. |
| R002 | vague-language | warning | Unenforceable phrases: "try to", "when possible", "盡量", "適當", etc. Skips definition context (e.g. "forbidden: 大概"). |
| R003 | redundancy | warning | Sections with >70% TF-IDF cosine similarity. Skips parent-child pairs. |
| R004 | dead-reference | error | Local file paths that don't exist. Filters out version numbers, cloud IAM roles, and wildcards. |
| R005 | contradiction | warning | Keyword pairs that conflict: "always" vs "never", "直接做" vs "先確認", etc. |
Deep mode
ailint --deep invokes the claude CLI to perform semantic contradiction detection beyond keyword matching. It finds contradictions that static rules miss — like "use barrel files" conflicting with "never use barrel exports" in the same config.
Requires Claude Code installed and authenticated.
Install
pip install airulelint # standard
pipx install airulelint # recommended on macOS with Homebrew Python
The PyPI package is airulelint — the CLI command it installs is ailint.
CLI reference
usage: ailint [-h] [--deep] [--format {text,json,github}]
[--severity {info,warning,error}] [--no-color] [--version]
[path]
positional arguments:
path Path to config file (auto-detects if omitted)
options:
--deep LLM-powered semantic analysis (requires claude CLI)
--format Output format: text (default), json, github
--severity Minimum severity to report: info, warning, error
--no-color Disable ANSI colors
--version Show version
The story
I spent months adding rules to my CLAUDE.md until it hit 3,550 lines. Then I analyzed which rules Claude actually followed — turns out, text rules have near-zero enforcement. I refactored to ~400 lines and moved everything else to hooks. This tool checks for the structural problems I found in my own file.
Contributing
Issues and pull requests welcome. To run tests:
pip install -e ".[test]"
pytest
License
MIT
Metadata
Release files for airulelint 0.1.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 | Provenance | Actions |
|---|---|---|---|---|
| airulelint-0.1.0.tar.gz | 14.2 kB | Without provenance | Details for airulelint-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| airulelint-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for airulelint-0.1.0-py3-none-any.whl |
Total release size: 29.8 kB
Release files / airulelint-0.1.0.tar.gz
| Download URL | airulelint-0.1.0.tar.gz |
|---|---|
| Size | 14.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ee710d1a24cea2596140423bc6957878d3215ef0765046f6dd8d46dc0ca56121
|
|
BLAKE2b-256 checksum How to use checksums |
2c8d1732ff91eebaa96d867e5315f466ad5dbf2c4d7e3a8c73f7589ccd22e77b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / airulelint-0.1.0-py3-none-any.whl
| Download URL | airulelint-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
83a4892fbe5fbeb39c6dd631d922fb4fdc92046adc7bca096fc33025514ab27b
|
|
BLAKE2b-256 checksum How to use checksums |
636b4a17a43d36648960419bc630d11e91d7ccb5c690acc28dacfc9727b17033
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for airulelint 0.1.0
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.