AgentLint

Lint your AI agent instruction files. Find broken rules, cut token waste, and know exactly what you're spending.

The first linter built specifically for AI agent instruction files. 67 rules catch vague language, security leaks, structural issues, and prompt anti-patterns — then cost analysis shows you exactly how much your context files cost per month and where to save. Works in VS Code and Cursor, across Claude Code, Cursor, and GitHub Copilot instruction files.

How AI-Ready Is Your Codebase?

Find out in 5 seconds. Open the Command Palette (Cmd+Shift+P) and run:

AgentLint: AI-Readiness Report

You'll get an instant, comprehensive audit of your entire agent setup — a 0-100 readiness score, your maturity level (L0–L6), a dollar-per-month cost breakdown of every instruction file, concrete savings you can action today, and a prioritized adoption roadmap showing exactly what to fix next. No API key needed.

Whether you're just getting started with a CLAUDE.md or running a multi-tool setup with skills, rules, and hooks — this tells you exactly where you stand and what's costing you money.

The Problem

You write a 300-line CLAUDE.md. Claude ignores half of it. You don't know which half — but you're paying for all of it.

Hedging language like "try to" is treated as optional. Vague instructions waste tokens on things the AI already does. Contradictory rules cancel each other out. Exposed API keys sit in plain text. And bloated files degrade adherence for ALL your rules — not just the ones at the end. Meanwhile, every token in your always-loaded instruction files is sent with every single message, costing $30-50/month per developer in input tokens alone.

AgentLint catches the problems you can't see and quantifies the waste in dollars — so you get better AI behavior AND lower costs.

What You Get

67 Lint Rules — Catch What You Can't See

Phase 1 — Local Rules (free, instant, every save)

Most rules have one-click quick-fixes in VS Code.

Phase 2 — Deep Analysis (optional, requires API key) Claude reviews your files for semantic issues rules can't catch: conflicting instructions, stale references, missing verification steps, instruction overload.

Cost Analysis — Know What You're Spending

> AgentLint: AI-Readiness Report

## Executive Summary

| Metric                    | Value                                    |
|---------------------------|------------------------------------------|
| AI Readiness Score        | 48/100 (Grade: D)                        |
| Monthly Context Cost      | ~$37.78/developer                        |
| Potential Monthly Savings | ~$8.12/developer (21% reduction)         |
| Best Suited For           | Claude Code (4/10 features)              |

## Token Budget & Cost Impact

| Category         | Files | Tokens  | $/month |
|------------------|-------|---------|---------|
| Always loaded    | 2     | ~5,465  | $27.05  |
| Conditional      | 4     | ~5,417  | ~$10.73 |
| On-demand        | 3     | ~1,432  | ~$0.00  |

### Potential Savings: ~$8.12/month ($97.44/year)

| Optimization                          | Monthly Savings |
|---------------------------------------|-----------------|
| Move specialized content to Skills    | $4.02           |
| Remove 18 discoverable info lines     | $2.48           |
| Convert prose to bullets (12 blocks)  | $1.19           |
| Remove 4 vague/redundant instructions | $0.43           |

Every file classified by how it's loaded (always, conditional, on-demand), with per-file $/month cost and concrete savings recommendations.

AI Tool Fit — Multi-Tool Aware

AgentLint doesn't just lint Claude files. It scores your setup across all three major AI coding tools:

| Tool           | Configured | Score |
|----------------|------------|-------|
| Claude Code    | ████░░░░░░ | 4/10  |
| Cursor         | ███        | 3/3   |
| GitHub Copilot | █░         | 1/2   |

Detects which tool your codebase is best configured for and flags when you're "multi-tool ready."

Readiness Score & Maturity Roadmap

Score (0-100) with letter grade, combining good-practice bonuses and issue penalties.

Maturity progression from L0 to L6:

Adoption roadmap grouped by effort — Quick Wins, Medium Effort, Strategic — each with points recoverable and $/month savings.

Supported Files

Quick Start

1. Install from the VS Code marketplace (search "AgentLint")
2. Open any supported file — diagnostics appear instantly with inline warnings and quick-fixes
3. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and explore:

For deep analysis (Phase 2), add your Anthropic API key:

// .vscode/settings.json
{
  "agentlint.anthropicApiKey": "sk-ant-..."
}

Or set the ANTHROPIC_API_KEY environment variable.

Configuration

Create a .agentlint.json in your project root:

{
  "disabledRules": ["PROSE_PARAGRAPH"],
  "disabledCategories": ["copilot"],
  "severityOverrides": {
    "HEDGING_LANGUAGE": "error",
    "FILE_TOO_LONG": "info"
  },
  "overrides": [
    {
      "files": ".claude/rules/*.md",
      "disabledRules": ["FILE_TOO_LONG"]
    }
  ]
}

In VS Code, you can also point to a specific config file:

// .vscode/settings.json
{
  "agentlint.configPath": "configs/.agentlint.json"
}

VS Code Settings

Built On Research

AgentLint's rules aren't opinions — they're based on documented findings:

• Anthropic's CLAUDE.md documentation — file hierarchy, recommended structure, line limits
• Boris Cherny's best practices (Claude Code tech lead) — verification gives 2-3x quality improvement
• Agent Skills specification (agentskills.io) — progressive disclosure, token budgets, frontmatter requirements
• LLM instruction adherence research — adherence degrades uniformly beyond recommended limits
• RFC 2119 keyword effectiveness — MUST/NEVER/ALWAYS followed more reliably than hedging language
• ETH Zurich study — auto-generated boilerplate decreases success rates by 2-3%

Early Development — Feedback Welcome

AgentLint is still in early development and evolving fast. If you try it out, we'd love to hear from you — what worked, what didn't, what you'd want next. Every piece of feedback helps shape where this goes.

• Leave a review on the VS Code Marketplace
• Star the repo on GitHub — it helps more people find it
• Follow @kcotias for updates on new features and releases
• Open an issue if you hit a bug or have an idea — github.com/kcotias/agentlint/issues

Thanks for being an early adopter.

License

MIT