seojoonkim/agentlinter

🧬 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): A10K

🕐 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 

---

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

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