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 --deep mode 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

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