AgentLint — Summary

AgentLint is a harness linter — a CLI tool and Claude Code plugin that scores agent configuration files (CLAUDE.md, AGENTS.md, .cursor/rules/, CI configs, hooks, .gitignore) across 58 deterministic checks in 6 dimensions (Findability, Instructions, Workability, Continuity, Safety, Harness) plus 7 opt-in AI-powered checks.

Problem it solves: Agent harnesses (the files that wrap an LLM and turn it into a coding agent) are routinely misconfigured — instruction files too long, hook event names misspelled, secrets in .gitignore blind spots, pre-commit hooks too slow for Claude Code, missing handoff files. AgentLint quantifies harness quality with a 0-100 score backed by empirical data from 265 versions of Anthropic's Claude Code system prompt and analysis of 492 public CLAUDE.md files.

Distinctive trait: Every check cites a source (Anthropic system prompt changelog, Claude Code source code, academic papers, production audits). The Harness dimension checks Claude Code-specific behaviors that no other tool validates — e.g., H1 (hook event name typos silently prevent hooks from firing), H3 (Stop hooks without circuit breakers run forever), H4 (wildcard auto-approve grants unlimited tool execution).

Target audience: Development teams running Claude Code, Cursor, or Codex who want a measurable, evidence-backed quality score for their agent harness, with a guided fix plan.

Production-readiness: Active (v1.1.13, last commit 2026-05-24), MIT license, 33 stars. Ships as npm package with 4 binary aliases (agentlint, agentlint-ai, agent-lint, al-scan) and a /al Claude Code slash command.

Differs from seeds: Most similar to spec-kit (CLI tool that checks agent configurations) but AgentLint audits the harness rather than the workflow. Unlike spec-kit's command/skill mirror pattern enforcing spec-driven development, AgentLint is a static analyzer with 58 evidence-backed checks against harness quality dimensions. The Session extended checks read Claude Code session logs — a capability unique in the corpus.

AgentLint — Overview

Origin

AgentLint was created by 0xmariowu and framed around Mitchell Hashimoto's February 2026 formulation: "Agent = Model + Harness." The tool was built after analyzing 265 versions of Anthropic's Claude Code system prompt, reading Claude Code source code for hard limits, and running audits against 492 public CLAUDE.md files.

Philosophy

From the README:

"ESLint was for the code humans wrote. AgentLint is for the context agents read."

"Agent = Model + Harness. If you're not the model, you're the harness."

"LangChain's February 2026 report: 70% of agent performance lives outside the model. Same weights, different harness, different results."

"A bad harness is worse than no harness. And almost nobody knows what a good one looks like. AgentLint is the first linter for the harness itself."

Evidence-First Methodology

Every check is backed by empirical data:

• 265 versions of Claude Code's system prompt tracked word-by-word (e.g., "When they cut IMPORTANT from 12 uses to 4, we knew.")
• Claude Code source code for hard limits (40K char truncation, 256KB file read limit, pre-commit hook timeout behavior)
• Real production audits of open-source codebases
• 6 academic papers on instruction compliance, context-file effectiveness, documentation decay

Key data points from the README:

• Median CLAUDE.md compliance across 492 files: 3/12 rules
• Perfect (12/12) scores: 0
• Most-missed rule: "don't edit out of scope" — 98% missed
• ETH Zurich: auto-generated context files reduce agent success in 5/8 settings

Check Dimensions

AgentLint — Architecture

Distribution

• Type: npm package + Claude Code plugin (opt-in)
• Package: agentlint-ai on npm (v1.1.13)
• License: MIT

Install Methods

npm install -g agentlint-ai        # CLI only — no Claude plugin yet
npx agentlint-ai install           # opt-in: register /al Claude Code plugin

CLI Binaries (4 aliases)

Required Runtime

• Node.js
• jq (JSON processing)
• Optional: Claude Code (for Deep/Session extended checks)

Directory Structure

AgentLint/
├── .claude-plugin/          # Claude plugin manifest
├── commands/
│   ├── al.md               # /al slash command (interactive scan-fix-report)
│   └── setup.md            # Setup command
├── hooks/
│   └── hooks.json          # SessionStart hook (dependency check)
├── scripts/
│   ├── agentlint.sh        # Main CLI entry point
│   └── (scanner)
├── src/
│   ├── scanner.sh          # al-scan binary
│   └── (check implementations)
├── standards/              # Documentation of checks and evidence
├── templates/              # Report templates
├── tests/                  # Test suite
├── docs/                   # GitBook documentation
└── package.json

Hook Events

Single hook — only a readiness check at session start, not an enforcement hook.

Plugin Data

Config stored at ${CLAUDE_PLUGIN_DATA}/config.json:

{
  "projects_root": "~/Projects",
  "modules": { "core": true, "deep": false, "session": false }
}

Target AI Tools

• Claude Code (primary — via /al slash command and plugin)
• Codex and Cursor (via CLI agentlint check)
• GitHub Actions (via action.yml)

AgentLint — Components

CLI Binaries (4)

Commands (2 Claude Code slash commands)

Hooks (1)

GitHub Action

action.yml — runs core 51 checks in CI on every PR that modifies CLAUDE.md / AGENTS.md. Reports compliance score in GitHub Actions summary.

Check Catalog (58 total)

Findability (F1–F9): Entry file exists, project description in first 10 lines, conditional loading guidance, large directory INDEX, resolved references, standard naming, @include resolution, glob frontmatter, no unfilled template placeholders.

Instructions (I1–I8): Emphasis keyword count, keyword density, rule specificity, action-oriented headings, no identity language, length 60-120 lines, under 40K chars, total injected content within 200K budget.

Workability (W1–W11): Build/test commands documented, CI exists, tests exist (non-empty), linter configured, no files over 256KB, fast pre-commit hooks, local fast test command, npm test script, release workflow version consistency, test cost tiers, feat/fix commits paired with test commits.

Continuity (C1–C6): Document freshness, handoff file exists, changelog has "why", plans in repo, CLAUDE.local.md not in git, HANDOFF.md has verify conditions.

Safety (S1–S9): .env in .gitignore, Actions SHA pinned, secret scanning configured, SECURITY.md exists, workflow permissions minimized, no hardcoded secrets (pattern match), no personal paths, no pull_request_target, no personal email in git history.

Harness (H1–H8): Hook event names valid, PreToolUse hooks have matcher, Stop hook has circuit breaker, no dangerous auto-approve, env deny coverage complete, hook scripts network access, gate workflows are blocking, hook errors use structured format.

Deep (opt-in, 3): AI-powered instruction contradiction detection, dead weight identification, vague rule analysis.

Session (opt-in, 4): Claude Code session log analysis for recurring issues, missed checks, tool abuse patterns, session efficiency.

AgentLint — Uniqueness

Differs from Seeds

AgentLint is closest to spec-kit (CLI tool for agent configuration quality) but operates at a fundamentally different layer. Spec-kit checks whether a project follows a spec-driven development workflow; AgentLint checks whether the agent's configuration files are correctly structured for reliable operation. Unlike any seed framework, AgentLint has a Harness dimension that specifically validates Claude Code hook configurations — checking for silent failure modes like typo'd event names, missing matchers on PreToolUse, Stop hooks without circuit breakers, and dangerous wildcard auto-approve. The Session extended mode is unique in the corpus: no other framework reads past Claude Code session logs to analyze agent behavior patterns. Unlike ccmemory which adds memory capabilities, AgentLint audits whether existing configuration enables reliable agent operation.

Key Differentiators

1. Harness-specific checks: H1-H8 validate Claude Code hook configurations at a level no other framework addresses — event name validation, matcher requirements, circuit breaker enforcement.
2. Session log analysis: Extended Session checks read ~/.claude/ session logs to find recurring issues from actual agent behavior.
3. Evidence-backed checks: 265 system prompt versions tracked, source code read for hard limits, 492 production audits for empirical baselines.
4. ETH Zurich finding: Explicitly warns against auto-generated context files (which the study found reduced agent success in 5/8 settings).
5. 4 CLI aliases: Usability focus — agentlint, agent-lint, agentlint-ai, al-scan.

Positioning

AgentLint is the only framework in the corpus positioned as a "harness linter" — applying software quality tooling concepts (ESLint → AgentLint) to the configuration layer of AI coding agents. It occupies the meta-tooling niche: a tool to assess the quality of other tools' configurations.

Observable Failure Modes

• False negatives on keyword density: I1 checks IMPORTANT keyword count based on Anthropic's internal count (4 uses), but projects legitimately have different emphasis requirements.
• Static-only H checks: H6 checks "hook scripts network access" but can't actually execute the hook to verify; relies on pattern matching.
• Session analysis depends on local logs: The Session module requires Claude Code session logs to be present at ~/.claude/ — unavailable in CI.
• Evidence dated to May 2026: System prompt analysis reflects 265 historical versions; the 266th version could change optimal parameters.
• Score gaming: The 12-rule keyword signal detection in the related cc-audit tool is deliberately permissive; a well-formatted nonsense file could score well.

Explicit Antipatterns

• * or .* auto-approve in Claude Code permissions (unlimited tool execution)
• Hook event name typos (PoToolUse vs PostToolUse)
• Stop hooks without circuit breakers
• IMPORTANT keyword overuse (diminishing compliance returns)
• Auto-generated context files from AI tools
• Files over 40K characters (silently truncated)
• Pre-commit hooks that take >30s (Claude Code never uses --no-verify)