Lints and scores the setup files of AI coding agents such as CLAUDE.md and AGENTS.md, checks supply chain risks, and analyzes session logs. Works with Claude Code, Codex, and Cursor.
Claude Code
> /plugin marketplace add 0xmariowu/AgentLint> /plugin install agent-lint@agent-lint
GitHub Copilot
$ copilot plugin marketplace add 0xmariowu/AgentLint$ copilot plugin install agent-lint@agent-lint
Agent = Model + Harness. The model isn't the bottleneck anymore โ the harness is.
Your
AGENTS.md,CLAUDE.md, CI config, hooks, and.gitignoreare 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 ยท ไธญๆๅๅฎข.
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
agentlintCLI on$PATHand does not touch~/.claude/. The second command (one-time, opt-in) detects Claude Code, copies the/alslash 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.
$ /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
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.gitignore โ the deterministic constraints the agent can't overrideSECURITY.md, changelogs, handoff notes โ the context that survives across sessionsHarness 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:
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.
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:
IMPORTANT from 12 uses to 4, we knew. When they removed every "You are a helpful assistant..." identity section, we knew.--no-verify.If a check can't cite a source, it doesn't ship.
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).
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
Stars on GitHub
A development methodology for coding agents that makes the agent brainstorm before building, follow plans, run parallel work and finish branches in a disciplined way. You get fewer skipped steps and more consistent results from your coding assistant.
@obraHelps you take a change from a rough idea or bug report through to a tested, reviewed result, with each step handled by a focused skill. Its skills cover pinning down domain terms, designing module interfaces, diagnosing hard bugs, and reviewing changes against your repo's coding standards.
@mattpocockGives your coding agent a planning, testing and review routine to follow on every task. It plans before building, checks changes with tests, has a fresh reviewer look for regressions, and saves repeated wins as reusable skills.
@affaan-mDeveloper tools for working on the React codebase itself. Provides skills for extracting error messages, managing and debugging feature flags across release channels, running Flow type checks, and fixing lint and formatting issues before committing.
@facebookLints and scores the setup files of AI coding agents such as CLAUDE.md and AGENTS.md, checks supply chain risks, and analyzes session logs. Works with Claude Code, Codex, and Cursor. Install it with the command on its page. Free and open source.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it