Back to packageRELEASE DETAILS

0.1.0

PyPI

agentlint-dev

Lint, score, and optimize AI agent configuration files (CLAUDE.md, AGENTS.md, Cursor rules)

Published28 Mar 2026

Direct dependencies5

Transitive dependenciesNot calculated

README

Version 0.1.0 documentation

agentlint

Lint, score, and optimize your AI agent configuration files.

agentlint analyzes CLAUDE.md, AGENTS.md, Cursor rules, and other AI agent configs — and tells you exactly what's wrong and how to fix it.

Install

pip install agentlint

Usage

# Lint a file and show issues
agentlint lint CLAUDE.md

# Score your config from 0-100
agentlint score CLAUDE.md

# Generate an optimized version
agentlint optimize CLAUDE.md          # saves to CLAUDE.optimized.md
agentlint optimize CLAUDE.md --ai     # uses Claude API for smarter suggestions

# Show diff of what optimize would change
agentlint diff CLAUDE.md

# Scan entire directory for all config files
agentlint scan .

Lint Rules

Code	Severity	Description
`TOO_LONG`	❌ Error	File exceeds 80 lines — Claude starts ignoring instructions
`TOKEN_WASTE`	⚠️ Warning	Personality instructions waste tokens with little effect
`DUPLICATE_RULE`	⚠️ Warning	Same instruction repeated more than once
`CONTRADICTION`	❌ Error	Conflicting instructions cause unpredictable behavior
`MISSING_COMMANDS`	❌ Error	No shell commands defined — agent can't verify its work
`MISSING_STACK`	❌ Error	No tech stack defined — agent may make wrong assumptions
`AT_MENTION_ABUSE`	⚠️ Warning	Excessive @file refs embed large files every session
`NO_VERIFY_STEP`	❌ Error	No instructions for verifying changes work
`VAGUE_INSTRUCTION`	⚠️ Warning	Instruction too vague to be reliably actionable
`BLOAT_DETECTED`	⚠️ Warning	Lengthy procedures belong in skill files, not base config
`MISSING_NEVER`	⚠️ Warning	No prohibition rules — negative constraints are highly effective
`INSTRUCTION_LIMIT`	⚠️ Warning	Estimated 150+ instructions — models lose track

Scoring

Category	Points	What it measures
Length & Density	25	File size, no token waste, no duplicates
Specificity	25	Concrete rules, no vague/contradicting instructions
Structure	25	Headers, bullets, code blocks, no bloat
Completeness	25	Stack, commands, verify step, never rules

License

MIT

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 5

Native requirements

5 direct targetsNot calculated transitive count

Package / target	Requirement	Relationship
click Environment { "extras": "", "marker": null, "requires_python": ">=3.9", "evaluation": "NOT_EVALUATED" }	`click>=8.0`	runtime
rich Environment { "extras": "", "marker": null, "requires_python": ">=3.9", "evaluation": "NOT_EVALUATED" }	`rich>=13.0`	runtime
anthropic Environment { "extras": "", "marker": "extra == \"ai\"", "requires_python": ">=3.9", "evaluation": "NOT_EVALUATED" }	`anthropic>=0.30; extra == "ai"`	runtime
pytest-cov Environment { "extras": "", "marker": "extra == \"dev\"", "requires_python": ">=3.9", "evaluation": "NOT_EVALUATED" }	`pytest-cov>=4.0; extra == "dev"`	runtime
pytest Environment { "extras": "", "marker": "extra == \"dev\"", "requires_python": ">=3.9", "evaluation": "NOT_EVALUATED" }	`pytest>=7.0; extra == "dev"`	runtime