Agentlinter

<p align="center"> <img src="https://img.shields.io/badge/AgentLinter-v2.3.0-7c3aed?style=for-the-badge&logoColor=white" alt="AgentLinter" /> </p> <h1 align="center">🧬 AgentLinter</h1> <p align="center"> <strong>ESLint for AI Agents</strong> — Score, diagnose, and auto-fix your entire agent workspace. <br /> <em>Free & open source. Always will be.</em> </p> <p align="center"> <a href="https://agentlinter.com">Website</a> · <a href="#quick-start">Quick Start</a> · <a href="#eight-scoring-dimensions">Scoring</a> · <a href="#vs-anthropics-official-tools">Comparison</a> · <a href="#how-it-works">How it Works</a> </p> <p align="center"> <img src="https://img.shields.io/github/stars/seojoonkim/agentlinter?style=flat-square&color=f59e0b" alt="GitHub Stars" /> <img src="https://img.shields.io/badge/node-18%2B-brightgreen?style=flat-square" alt="Node 18+" /> <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License" /> <img src="https://img.shields.io/badge/frameworks-Claude_Code_%7C_OpenClaw_%7C_Moltbot_%7C_Cursor_%7C_Windsurf_%7C_Copilot-purple?style=flat-square" alt="Frameworks" /> </p>

---

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

| Problem | Impact | AgentLinter | |---------|--------|-------------| | 🔇 Vague instructions fail silently | "Be helpful" gives zero guidance | Detects ambiguity, suggests specifics | | 🔑 Secrets in plain text | API keys committed to repos | Scans for 20+ secret patterns | | 🔀 Multi-file drift | SOUL.md contradicts CLAUDE.md | Cross-file consistency checks | | 📉 No quality baseline | Can't measure improvement | 0–100 score across 8 dimensions | | 🏗️ Missing essentials | No error recovery, no boundaries | Completeness checklist with auto-fix | | ⚙️ Insecure runtime config | Gateway exposed to network | Runtime config security checks | | 🛠️ Dangerous skills | curl | bash in skill files | Skill safety scanning | | 🌐 Non-English config files | 2.5x token waste, interpretation errors | Detects non-English content, suggests translation |

---

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)

| Analyzer | Description | |----------|-------------| | Cognitive Load | Measures instruction density and mental overhead | | Token Heatmap | Visualizes token distribution across file sections | | Modularity | Evaluates separation of concerns and file organization | | Role Complexity | Detects over-complex role/persona definitions | | Security Scan | Deep security analysis with 25 patterns (up from 15) |

🎯 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/