Agent = Model + Harness. The model isn't the bottleneck anymore โ the harness is.
Your AGENTS.md, CLAUDE.md, CI config, hooks, and .gitignore are the harness. When they're wrong, Claude Code, Cursor, and Codex ship AI slop. When they're right, agents compound.
AgentLint scores your harness across 51 deterministic checks on 6 core dimensions, plus 7 opt-in extended checks (Deep + Session) that use AI sub-agents and local Claude Code session logs when available. Evidence-backed. Zero opinions.
๐ Full docs, 20+ long-form guides, and the complete check catalog live at agentlint.app. Highlights: Writing a Good CLAUDE.md ยท The 33-Check Catalog ยท AGENTS.md vs CLAUDE.md ยท ไธญๆๅๅฎข.
Install
npm install -g agentlint-ai # CLI only โ no Claude plugin yet
npx agentlint-ai install # opt-in: register /al Claude Code plugin
The first command installs the agentlint CLI on $PATH and does not touch ~/.claude/. The second command (one-time, opt-in) detects Claude Code, copies the /al slash command into ~/.claude/commands/, and registers the marketplace plugin. Side-effect details and uninstall path in INSTALL.md.
Then in any git repo:
agentlint check
In Claude Code (after running npx agentlint-ai install): run /al for the interactive scan-fix-report flow.
Using an AI coding agent? Point it at INSTALL.md โ it's written to be read once and acted on.
What you get
$ /al
AgentLint โ Score: 72/100 (core)
Findability โโโโโโโโโโโโโโโโโโโโ 7/10
Instructions โโโโโโโโโโโโโโโโโโโโ 8/10
Workability โโโโโโโโโโโโโโโโโโโโ 6/10
Safety โโโโโโโโโโโโโโโโโโโโ 5/10
Continuity โโโโโโโโโโโโโโโโโโโโ 7/10
Harness โโโโโโโโโโโโโโโโโโโโ 10/10
Deep โโโโโโโโโโโโโโโโโโโโ n/a (opt-in)
Session โโโโโโโโโโโโโโโโโโโโ n/a (opt-in)
Fix Plan (7 items):
[guided] Pin 8 GitHub Actions to SHA (supply chain risk)
[guided] Add .env to .gitignore (AI exposes secrets)
[assisted] Generate HANDOFF.md
[guided] Reduce IMPORTANT keywords (7 found, Anthropic uses 4)
Select items โ AgentLint fixes โ re-scores โ saves HTML report
The harness problem
In February 2026, Mitchell Hashimoto (HashiCorp) coined the term. OpenAI's Ryan Lopopolo formalized it days later. LangChain's Vivek Trivedy gave it the cleanest definition:
Agent = Model + Harness. If you're not the model, you're the harness.
The harness is every piece of code, configuration, and instruction that wraps an LLM and turns it into an agent. For coding agents, your harness includes:
AGENTS.md / CLAUDE.md โ the persistent rules injected at session start.cursor/rules/, .github/copilot-instructions.md โ tool-specific instruction layers- CI, pre-commit hooks,
.gitignore โ the deterministic constraints the agent can't override
SECURITY.md, changelogs, handoff notes โ the context that survives across sessions
Harness engineering is the discipline of designing those pieces so the agent stays reliable across hundreds of tool calls, not just the first ten.
The research is blunt:
- Anthropic's 2026 Agentic Coding Trends Report found that teams maintaining a good context file report 40% fewer "bad suggestion" sessions
- DORA 2025 State of AI-Assisted Software Development reached the same conclusion: AI is an amplifier โ it accelerates teams with good harnesses and amplifies dysfunction in teams without them
- An ETH Zurich study found that auto-generated context files actually reduce agent success rates in 5 of 8 tested settings, and increase inference cost by 20โ23%
- A randomized controlled trial found developers using AI were 19% slower on complex tasks โ while believing they were 20% faster
- LangChain's February 2026 report: 70% of agent performance lives outside the model. Same weights, different harness, different results.
Translation: 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.
What makes AgentLint different
Every check is backed by data, not opinions. The data comes from places most developers never look โ and it's what lets us measure harness health rigorously:
- 265 versions of Anthropic's own Claude Code system prompt โ we tracked every single word they added, deleted, and rewrote. When they cut
IMPORTANT from 12 uses to 4, we knew. When they removed every "You are a helpful assistant..." identity section, we knew.
- Claude Code source code โ which is where the harness hard limits live. 40,000-character entry files get silently truncated. 256 KB files can't be read at all. Pre-commit hooks that take too long cause commits to hang forever because Claude Code never uses
--no-verify.
- Real production audits across open-source codebases โ the security gaps that agents walk straight into.
- 6 academic papers on instruction compliance, context-file effectiveness, and documentation decay.
If a check can't cite a source, it doesn't ship.
What it checks
58 checks total: 51 deterministic core checks across 6 dimensions (always run), plus 7 opt-in extended checks (Deep: 3 AI-powered analysis checks; Session: 4 Claude Code log-reading checks). Default agentlint check and the GitHub Action only run the 51 core checks โ the extended ones need AI sub-agents or local Claude Code session logs, so they're opt-in via /al inside Claude Code.
The total score is averaged only over dimensions that actually ran. A default CI run shows Score: NN/100 (core) and marks Deep/Session as n/a, never as 0/10. When extended checks do run, the header shows (core+extended).
๐ Findability โ can AI find what it needs? (20%)
| Check | What | Why |
|---|
| F1 | Entry file exists | No CLAUDE.md / AGENTS.md = AI starts blind |
| F2 | Project description in first 10 lines | AI needs context before rules |
| F3 | Conditional loading guidance | "If working on X, read Y" prevents context bloat |
| F4 | Large directories have INDEX | >10 files without index = AI reads everything |
| F5 | All references resolve | Broken links waste tokens on dead-end reads |
| F6 | Standard file naming | README.md, CLAUDE.md are auto-discovered |
| F7 | @include directives resolve | Missing targets are silently ignored โ you think it's loaded, it isn't |
| F8 | Rule file frontmatter uses globs | .cursor/rules/ MDC files should match glob patterns, not exact paths |
| F9 | No unfilled template placeholders | {{variables}} left in context files waste tokens and confuse the model |
๐ Instructions โ are your rules well-written? (25% โ highest weight)
| Check | What | Why |
|---|
| I1 | Emphasis keyword count | Anthropic cut IMPORTANT from 12 to 4 across 265 versions |
| I2 | Keyword density | More emphasis = less compliance. Anthropic: 7.5 โ 1.4 per 1K words |
| I3 | Rule specificity | "Don't X. Instead Y. Because Z." โ Anthropic's golden formula |
| I4 | Action-oriented headings | Anthropic deleted all "You are a..." identity sections |
| I5 | No identity language | "Follow conventions" removed โ model already does this |
| I6 | Entry file length | 60โ120 lines is the sweet spot. Longer dilutes priority |
| I7 | Under 40,000 characters | Claude Code hard limit. Above this, your file is truncated โ silently |
| I8 | Total injected content within budget | All auto-injected files stay within the 200K context budget |
๐จ Workability โ can AI build and test? (18%)
| Check | What | Why |
|---|
| W1 | Build/test commands documented | AI can't guess your test runner |
| W2 | CI exists | Rules without enforcement are suggestions |
| W3 | Tests exist (not empty shell) | A CI that runs pytest with 0 test files always "passes" |
| W4 | Linter configured | Mechanical formatting frees AI from guessing style |
| W5 | No files over 256 KB | Claude Code cannot read them โ hard error |
| W6 | Pre-commit hooks are fast | Claude Code never uses --no-verify. Slow hooks = stuck commits |
| W7 | Local fast test command documented | Entry file documents a fast (<30s) test command for mid-session verification |
| W8 | npm test script exists | JS/Node repos need npm test so AI can run tests without guessing |
| W9 | Release workflow validates version consistency | Automated drift detection across package.json, CHANGELOG, and badges |
| W10 | Test cost tiers defined (pytest markers) | @pytest.mark.fast lets AI run the cheap subset, not the full 10-minute suite |
| W11 | feat/fix commits paired with test commits | Gate that catches features landing without corresponding tests |
๐ Continuity โ can the next session pick up? (12%)
| Check | What | Why |
|---|
| C1 | Document freshness | Stale instructions are worse than no instructions |
| C2 | Handoff file exists | Without it, every session starts from zero |
| C3 | Changelog has "why" | "Updated INDEX" says nothing. "Fixed broken path" says everything |
| C4 | Plans in repo | Plans in Jira don't exist for AI |
| C5 | CLAUDE.local.md not in git | Private per-user file โ must be in .gitignore |
| C6 | HANDOFF.md has verify conditions | Notes with evidence (score โฅ X, tests pass) let the next session skip full re-audit |
๐ Safety โ is AI working securely? (15%)
| Check | What | Why |
|---|
| S1 | .env in .gitignore | AI's Glob tool ignores .gitignore by default โ secrets visible |
| S2 | Actions SHA pinned | AI push triggers CI. Floating tags = supply chain attack vector |
| S3 | Secret scanning configured | AI won't self-check for accidentally written API keys |
| S4 | SECURITY.md exists | AI needs security context for sensitive code decisions |
| S5 | Workflow permissions minimized | AI-triggered workflows shouldn't have write access by default |
| S6 | No hardcoded secrets | Detects sk-, ghp_, AKIA, private key patterns in source |
| S7 | No personal paths in source | Absolute home-dir paths leak machine identity and break on other machines |
| S8 | No pull_request_target trigger | Runs in privileged context โ supply chain attack vector for external PRs |
| S9 | No personal email in git history | Personal email in commits is a privacy and identity leak |
โ๏ธ Harness โ is your Claude Code setup correct? (10%)
| Check | What | Why |
|---|
| H1 | Hook event names valid | PoToolUse vs PostToolUse โ typos silently prevent hooks from ever firing |
| H2 | PreToolUse hooks have matcher | Without a tool matcher, the hook runs before every tool call |
| H3 | Stop hook has circuit breaker | Stop hooks without an exit condition run forever |
| H4 | No dangerous auto-approve | * or .* grant unlimited tool execution with no human check |
| H5 | Env deny coverage complete | Missing deny patterns let secrets leak to untrusted tools |
| H6 | Hook scripts network access | Outbound calls from hooks can exfiltrate data triggered by the agent |
| H7 | Gate workflows are blocking | Warn-only CI gates are effectively disabled โ agents merge despite failures |
| H8 | Hook errors use structured format | what/rule/fix lets the agent self-correct; unstructured errors leave it stuck |
๐ง Deep โ AI-powered instruction analysis (opt-in, extended)
Spawns AI subagents to find what pattern-matching can't:
| Check | What | Why |
|---|
| D1 | Contradictory rules | Two rules that conflict cause the model to pick one โ usually the wrong one |
| D2 | Dead-weight rules | Rules the model would follow anyway waste tokens and dilute priority |
| D3 | Vague rules without decision boundary | "Use good judgment" gives the model nothing to evaluate against |
๐ Session โ learn from your Claude Code logs (opt-in, extended)
Reads your session history to surface patterns you'd never notice manually:
| Check | What | Why |
|---|
| SS1 | Repeated instructions | Instructions you type every session belong in CLAUDE.md |
| SS2 | Ignored rules | Rules AI keeps bypassing need rewriting, not repeating |
| SS3 | Friction hotspots | Which projects and tasks generate the most re-work |
| SS4 | Missing rule suggestions | Common corrections that aren't captured anywhere yet |
How is this different from /init?
/init generates a template CLAUDE.md from scratch. Useful on day one. Useless on day fifty โ when the file is stale, bloated with emphasis keywords the model ignores, missing .env in .gitignore, and silently exceeds the 40K hard limit.
/init writes a file. AgentLint audits the whole system:
| /init | AgentLint |
|---|
Generates template CLAUDE.md | โ
| โ |
| Checks entry-file quality | โ | โ
|
Finds broken @include references | โ | โ
|
| Enforces the 40K character hard limit | โ | โ
|
Audits CI, hooks, .gitignore, Actions SHA pinning | โ | โ
|
| Detects instruction rot over time | โ | โ
|
| Audits Claude Code hook configuration | โ | โ
|
| Auto-fixes what it can | โ | โ
|
| Every check backed by a cited data source | โ | โ
|
Who this is for
- Solo developers using Claude Code, Cursor, or Codex who want the agent to stop ignoring your rules
- Team leads who need every repo in the org to be AI-ready before agents ship to prod
- OSS maintainers whose external contributors (and their agents) should write code in your style
- Security-conscious engineers worried about agents exfiltrating
.env or triggering vulnerable workflows
Compatibility
AgentLint ships as a Claude Code plugin and standalone CLI. When it runs, it audits any of the following if present in your repo:
CLAUDE.md (Anthropic's Claude Code)AGENTS.md (the universal standard โ used by OpenAI Codex, Cursor, Windsurf, Kilo, GitHub Copilot, Gemini CLI, and 60,000+ open-source repos).cursor/rules/.github/copilot-instructions.md
Roadmap: native Cursor and Codex integrations. Star the repo to follow.
Update
npm install -g agentlint-ai
Or update the Claude Code plugin directly:
claude plugin update agent-lint@agent-lint
Evidence
Every check cites its source. No opinions, no best practices โ data.
Full citations in standards/evidence.json.
FAQ
The term got popular in early 2026 (Mitchell Hashimoto, OpenAI, LangChain). Shortest definition: Agent = Model + Harness. The harness is everything that wraps an LLM and turns it into an agent โ tools, state management, feedback loops, and the persistent rules it reads at session start. For coding agents, that last part is your AGENTS.md, CLAUDE.md, .cursor/rules, CI, pre-commit hooks, and .gitignore. AgentLint is the first linter built specifically to audit that layer.
See the table above. /init writes a file; it doesn't audit your repo. AgentLint does 51 deterministic checks across 6 core dimensions (plus 7 opt-in extended checks) โ and fixes what it finds.
Today AgentLint runs inside Claude Code, but the checks apply to repo assets every agent reads: AGENTS.md, .cursor/rules, .github/copilot-instructions.md. A well-linted repo makes every agent better, not just Claude. Native Cursor and Codex integrations are on the roadmap.
It depends on which mode you run. The default (agentlint check and the GitHub Action) is local-only and runs zero AI. The two opt-in extended modes do touch AI or local session logs โ we spell it out so there's no surprise:
| Mode | Data accessed | Network / AI |
|---|
agentlint check (default) | files in the repo being scanned | Local only, no AI |
| GitHub Action | files in the checked-out repo inside the runner | Local only, no AI |
/al (core dims only) | git repos under the configured PROJECTS_ROOT | Local only, no AI |
/al with Deep (opt-in) | selected entry files (e.g. CLAUDE.md) | Sends file contents to a Claude sub-agent |
/al with Session (opt-in) | ~/.claude/projects/ logs on your machine | Local analyzer. Output is redacted by default; raw snippets require --include-raw-snippets |
Deep is the only mode that transmits file contents off your machine, and it only runs when you explicitly ask for it inside Claude Code. Everything the default scan produces โ the Score: NN/100 (core) output, the JSONL, the SARIF, the GitHub Action annotations โ comes from pattern checks on disk, no API calls.
No. npm install -g agentlint-ai only installs the agentlint CLI to npm's global prefix (just like any other CLI tool). The Claude Code plugin install is opt-in: run npx agentlint-ai install (one-time) to detect Claude Code and register the /al slash command in ~/.claude/commands/. The CLI works without that step; the /al slash command does not.
Failure-mode fallbacks live in INSTALL.md.
No. Every check cites a specific source โ Anthropic's 265 prompt versions, Claude Code source code, peer-reviewed papers, or real production audits. If a check can't be backed by data, it doesn't ship.
Because good context engineering is cross-tool. If you're using any combination of Claude Code, Cursor, and Codex, the same AGENTS.md serves all of them. AgentLint checks it against the same evidence base regardless of which agent ends up reading it.
Under 5 seconds for most repos. The Deep and Session dimensions take longer because they spawn subagents or read session logs.
Requirements
- Node 20+
jq- Claude Code (for
/al plugin and Deep/Session analysis)
Contributing
Issues and PRs welcome. See CONTRIBUTING.md.
License
MIT
If AgentLint saved you from one bad agent session, please โญ star the repo โ it's how we find out it's useful.
Built by @0xmariowu ยท agentlint.app
