🧬 AgentLinter

ESLint for AI Agents — Score, diagnose, and auto-fix your entire agent workspace.
Free & open source. Always will be.

Website · Quick Start · Scoring · Comparison · How it Works

Why AgentLinter?

Your AI agent is only as good as its config files. A vague CLAUDE.md produces vague results. A leaked API key becomes a vulnerability. Contradictions across files cause unpredictable behavior.

"Be specific: 'Use 2-space indentation' is better than 'Format code properly.'"
— Anthropic, CLAUDE.md Best Practices

AgentLinter treats your agent config as code — scanning, scoring, and fixing it with the same rigor you'd apply to source code.

The problems it solves

Quick Start

npx agentlinter

That's it. Free, open source, forever. No config. No API key. No signup. No paywall. Runs in seconds.

🔍 AgentLinter v0.2.0
📁 Scanning workspace: .claude/ + root
   Found 5 files: CLAUDE.md, SOUL.md, USER.md, TOOLS.md, SECURITY.md

  Workspace Score ........ 76/100  (B+)
  ├─ Structure     ████████░░  80
  ├─ Clarity       ███████░░░  70
  ├─ Completeness  ██████░░░░  60
  ├─ Security      █████████░  90
  ├─ Consistency   ██████░░░░  60
  ├─ Memory        ████████░░  80
  ├─ Runtime Cfg   █████████░  88
  └─ Skill Safety  █████████░  92

  2 critical(s) · 3 warning(s)

  🔴 CRITICAL  TOOLS.md:14 — Secret: API key pattern "sk-proj-..."
  🔴 CRITICAL  SOUL.md ↔ CLAUDE.md — Conflicting persona definition
  ⚠️  WARN  CLAUDE.md:28 — Vague: "be helpful" → be specific
  ⚠️  WARN  No error recovery strategy defined
  ⚠️  WARN  2 cross-file references broken

  💡 3 issues with suggested fixes. See report for details.
  📊 Report → agentlinter.com/r/a3f8k2

Commands

# Score your workspace
npx agentlinter

# Auto-fix safe issues
npx agentlinter --fix

# Bootstrap a new workspace from template
npx agentlinter init --template coding

# Share your score
npx agentlinter share

🆕 What's New in v2.3.0

Algorithm fairness — Korean workspace support, false positive filtering, and skills budget separation.

🇰🇷 Korean Workspace Support

• Expanded escape hatch detection — Korean escape patterns (때만, 경우에만, 지시할 때, 상황에서만, 허용, 예외 없음) now recognized
• Wider context window — Escape hatch search expanded from 3 to 7 lines for better Korean document structure
• Non-English severity downgrade — english-config-files now reports as info instead of warning

🎯 False Positive Filtering

• Backtick reference filtering — Skips JS property access (process.env), domains (.com, .kr), OAuth IDs (5+ digits), URL patterns, and code patterns
• MEMORY.md cleanup — Removed stale file path references that triggered false positives

📊 Skills Budget Separation

• On-demand skills excluded from hard limit — Only core files (CLAUDE.md + rules + agents) count against the 150-instruction budget
• Skills shown separately — Skills display with "(on-demand, not counted against limit)" label

🏷️ Skill Author Field

• Batch author addition — All skill files now include author in frontmatter for proper attribution

What's in v2.2.0

38+ rules with token budget analysis, injection defense, cognitive blueprint validation, and multi-framework export.

📊 Token Budget Linter Enhanced (+4 rules)

• token-budget/total-tokens — Byte/token measurement with numeric thresholds (current: X tokens, recommended: ≤3000)
• token-budget/section-weight — Identifies heaviest sections by token proportion (e.g., "## Tools dominates at 45%")
• token-budget/compressible-padding — Detects filler phrases: "Always remember to", "Make sure to", "It is important to"
• token-budget/under-150-tokens — Warns when files have fewer than 150 tokens (too sparse)

🛡 Prompt Injection Defense (+1 rule)

• security/no-injection-defense — Comprehensive injection defense check:
  • Injection defense keywords (prompt injection, untrusted input, jailbreak)
  • External content/URL handling guidance (sub-agent isolation, sanitization)
  • Permission boundaries: NEVER/DO NOT pattern count (recommend ≥2)
  • Suggests SECURITY.md file if missing

🧠 Cognitive Blueprint (+3 rules, NEW category)

• blueprint/coverage — 6-element cognitive blueprint coverage check:
  • Identity: Agent name/role/persona definition
  • Goals: Purpose/mission/objectives
  • Constraints: NEVER/forbidden boundaries
  • Memory: Persistence/retention strategy
  • Planning: Step/workflow/procedure definitions
  • Validation: Verify/check/confirm procedures
• blueprint/identity-defined — Dedicated identity check
• blueprint/constraints-defined — Dedicated constraints check
• Coverage ≤3/6 → error, <6/6 → warning
• Output: Blueprint Coverage: 4/6 (Identity ✅ Goals ✅ Constraints ✅ Memory ❌ Planning ✅ Validation ❌)

📤 Multi-Framework Export (NEW)

Convert your CLAUDE.md to other framework formats:

# Export to Cursor
npx agentlinter export --format cursor    # → .cursorrules

# Export to GitHub Copilot
npx agentlinter export --format copilot   # → .github/copilot-instructions.md

# Export to Gemini CLI
npx agentlinter export --format gemini    # → GEMINI.md

Strips Claude-specific directives while preserving coding style, project structure, and rules.

What's in v2.1.0

30 rules (13 new) with freshness detection, import validation, multi-framework support, and research-backed linting.

📊 Token Bloat Score Enhanced (+3 rules)

• clarity/duplicate-content — 3-gram Jaccard similarity detects duplicate sections (>= 60%)
• clarity/obvious-statements — Flags "be accurate", "follow instructions" etc. that waste tokens
• clarity/token-budget-range — Token-estimated grading (Korean-corrected): A<=2K, B<=5K, C<=10K, D>10K

🕐 Freshness / Staleness Detector (+3 rules, NEW)

• consistency/stale-file-reference — Validates file paths referenced in markdown
• consistency/stale-date — 90d+ warning, 180d+ error for outdated dates
• consistency/stale-package-reference — Cross-checks packages against package.json

📎 Import Validator (+2 rules, NEW)

• structure/dead-import — Validates @file.md references exist
• structure/circular-import — DFS cycle detection in import graph

🔀 Multi-Framework Support (+4 rules, NEW)

• Cursor (.cursorrules): cursor/rules-format, cursor/no-conflicting-claude
• GitHub Copilot (.github/copilot-instructions.md): copilot/instructions-format, copilot/no-conflicting-claude

✍️ Descriptive Ratio (+1 rule)

• claude-code/descriptive-ratio — Warns when >60% of content is descriptive instead of imperative

📚 Research-backed

• Rules grounded in prompt engineering best practices
• Reference: Gloaguen et al. (2026) — "A Taxonomy of Agent Instruction Failures"

What's in v2.0.0

Major upgrade with v2 analysis engine, advanced scoring, and new APIs.

🧠 v2 Analyzers (5 new analysis modules)

🎯 Clarity Score

Detects 17 ambiguous patterns in both Korean and English:

• Vague conditionals, naked pronouns, undefined references
• Weighted scoring with actionable rewrite suggestions
• Korean token correction for accurate estimation

💡 Actionable Suggestions

Every issue now comes with a priority level:

• HIGH — Fix immediately, directly impacts agent behavior
• MED — Should fix, improves reliability
• LOW — Nice to have, minor improvement

🏷️ Badge API

Embed your AgentLinter score in your README:

![AgentLinter Score](https://agentlinter.com/api/badge?score=87)

Endpoint: /api/badge?score=N — returns an SVG badge.

🔐 Security Patterns (25)

Expanded from 15 to 25 patterns including:

• AWS credential patterns, JWT tokens
• Injection vectors, role-hijacking attempts
• Enhanced API key detection (OpenAI, Anthropic, Google, GitHub, Vercel, Railway)

🌏 Korean Token Correction

Accurate token estimation for Korean agent files — fixes over-counting that caused inflated scores.

📦 Token Budget Estimator + .claudeignore

• Token Budget Estimator — calculates token usage per file with budget gauge
• .claudeignore Rules — define files to exclude from context window
• Token Map UI — visual breakdown of token allocation

Previous: v1.1.0

⚠️ Position Risk Warning

Rules buried in the middle of long files are often ignored by LLMs — studies show attention degrades significantly for content not near the beginning or end of context.

AgentLinter detects rules placed in dangerous middle positions and warns you:

⚠️  WARN  CLAUDE.md:145 — Position Risk: Critical rule in middle position
         (lines 100-180 of 300). LLMs may not attend to this.
         → Move to top section or add a "## 🚨 CRITICAL RULES" header.

📊 Token Efficiency Score

Grades each agent file by line count: A (≤150), B (≤300), C (≤500), D (>500).

🔒 Enhanced Security Check

Prompt Injection Vulnerability Detection + Enhanced API Key Exposure scanning.

Automatic Mode Detection

AgentLinter automatically detects whether you're running in Project Mode (Claude Code) or Agent Mode (OpenClaw/Moltbot/Clawdbot) and adjusts recommendations accordingly.

This means:

• Claude Code projects won't get recommendations for USER.md, memory strategies, or session handoff — those are OpenClaw patterns
• OpenClaw agents get the full rule set for persistent, multi-session agents

No configuration needed — it just works.

How it Works

1. 🔍 Scan

Discovers every .md file in your agent workspace — CLAUDE.md, SOUL.md, USER.md, TOOLS.md, SECURITY.md, .claude/rules/, skill files, and more.

Supports Claude Code, OpenClaw, Moltbot, Cursor, Windsurf, and any workspace following the Agent Skills open standard.

2. 📊 Score

Evaluates across eight dimensions, each scored 0–100. Every rule is documented and derived from Anthropic's official best practices plus patterns from high-performing agent workspaces.

3. ⚡ Fix

Every issue comes with a prescription. Most are auto-fixable with --fix:

• Secrets get flagged for immediate rotation
• Vague instructions get specific rewrites
• Missing sections get scaffolded
• Cross-file contradictions get highlighted with resolution suggestions

Ten Scoring Dimensions

Each dimension checks specific, documented rules:

Structure — 12%

File organization, naming conventions, section hierarchy.

Clarity — 20%

Instruction quality — can an AI agent unambiguously follow these?

Completeness — 12%

Does the workspace cover all essential aspects?

Security — 15%

Protecting your agent and your data.

Consistency — 8%

Cross-file coherence across the entire workspace.

Memory — 10%

Session handoff and knowledge persistence.

Runtime Config — 13%

OpenClaw/Gateway configuration security.

Skill Safety — 10%

Dangerous patterns in skill files.

Blueprint — 8%

Cognitive blueprint coverage — does the agent config define all essential elements?

Starter Templates

Bootstrap a new workspace with best practices built in:

npx agentlinter init --template <type>

Custom Rules

Enforce your team's standards with .agentlinterrc:

{
  "extends": "agentlinter:recommended",
  "rules": {
    "require-files": ["CLAUDE.md", "SECURITY.md"],
    "max-file-length": 300,
    "require-section": ["## Boundaries", "## Tools"],
    "no-vague-language": "error",
    "require-injection-defense": "error"
  },
  "ignore": ["drafts/"]
}

Score Reports & Sharing

Every run generates a web report with:

• Tier grade: S → A+ → A → B+ → B → C
• Category breakdown: Visual bars for each dimension
• Prescriptions: Exact issues with auto-fix markers
• Percentile ranking: Where you stand among all agents
• Progress tracking: Watch your score improve over time

Share on X

My AI agent scored 87/100 on @AgentLinter 🔍

Structure: 80 | Clarity: 90 | Security: 95

How sharp is YOUR agent?
→ agentlinter.com

VS Anthropic's Official Tools

Anthropic provides CLAUDE.md memory and skills — the building blocks for agent configuration. AgentLinter tells you if you're using them well.

Not a replacement — an extension. AgentLinter builds on Anthropic's CLAUDE.md standard and the Agent Skills open standard. Think of it as ESLint for JavaScript — the language gives you the syntax, the linter tells you if your code is good.

Self-Evolving Rules

AgentLinter gets smarter with every run:

Lint → Share → More Users → More Data → Better Rules → ↻

All data anonymized. Opt-out: --no-telemetry

CI/CD Integration

GitHub Action

# .github/workflows/agentlinter.yml
name: AgentLinter
on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npx agentlinter
      - run: npx agentlinter --format github

Score changes are posted as PR comments automatically.

Supported Frameworks

Privacy

Local-first by design. All scanning and scoring runs 100% on your machine. Your file contents never leave.

What stays local (always)

• ✅ Your actual file contents (CLAUDE.md, SOUL.md, etc.)
• ✅ System prompts and personal context
• ✅ Security rules and sensitive instructions

What's shared (only when report link is generated)

• 📊 Scores and grades
• 📄 File names (not contents)
• 💬 Diagnostic messages (e.g., "Line 28: vague instruction")

Options

• Use --local flag to skip sharing entirely — zero network calls
• Secrets are auto-masked in reports (API keys show as [REDACTED])
• No telemetry by default

Roadmap

• Core scoring engine (8 dimensions)
• Auto-fix with --fix
• Secret scanning (25 patterns)
• Cross-file consistency checks
• Web reports with sharing
• Runtime config audit
• Skill safety scanning
• GitHub Action marketplace release
• VS Code extension (real-time linting)
• Team dashboard
• Badge API (/api/badge?score=N)
• v2 Analyzers (Cognitive Load, Token Heatmap, Modularity, Role Complexity, Security Scan)
• Token Budget Estimator + .claudeignore
• Freshness/Staleness Detector + Import Validator
• Multi-framework support (Cursor, Copilot)
• Cognitive Blueprint Validation (10th scoring dimension)
• Multi-Framework Export (cursor, copilot, gemini)
• Leaderboard

Contributing

We welcome contributions! Areas where help is needed:

• New rules — See src/engine/rules/ for the pattern
• Framework support — Add parsers for new agent frameworks
• Templates — Create starter templates for new use cases
• Docs — Improve documentation and examples

git clone https://github.com/seojoonkim/agentlinter
cd agentlinter
npm install
npm run dev

License

MIT

📋 Version History

Full changelog: CHANGELOG.md

⭐ Star on GitHub · @simonkim_nft

Built on Anthropic's CLAUDE.md standard · Agent Skills open standard