> For the complete documentation index, see [llms.txt](https://docs.agentlint.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agentlint.app/intro.md).

# Introduction

**Your AI agent is only as good as your repo.** AgentLint finds what's broken — file structure, instruction quality, build setup, session continuity, security posture — and fixes it. 51 deterministic core checks (6 dimensions) + 7 opt-in AI-native analyzers, every one backed by data. Works across Claude Code, Codex, Cursor, Copilot, Gemini CLI, Windsurf, and Cline.

> We analyzed 265 versions of Anthropic's Claude Code system prompt, documented the hard limits, audited thousands of real repos, and reviewed the academic research. The result: a single command that tells you exactly what your AI agent is struggling with and why.

## Install

```bash
npm install -g agentlint-ai
```

Then in any git repo:

```bash
agentlint check
```

In Claude Code: run `/al` for the interactive scan-fix-report flow.

> **Using an AI coding agent?** Point it at [INSTALL.md](https://github.com/0xmariowu/AgentLint/blob/main/docs/content/INSTALL.md) — it's written to be read once and acted on.

## CLI commands

Once installed, you can also use AgentLint from any shell:

```bash
agentlint check                                    # diagnose (51 core checks, 6 dimensions)
agentlint fix W11                                 # fix a specific check directly
agentlint setup --lang ts .                       # bootstrap CI/hooks/templates
```

**setup** installs the full AI-native stack: 12 CI workflows, git hooks, CLAUDE.md template, plan format, compliance tests.\
**check** finds what's broken — file structure, instruction quality, build setup, continuity, security.\
**fix** applies the fixes automatically.

## GitHub Action

Create `.github/workflows/agentlint.yml`:

```yaml
name: AgentLint

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  agentlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: 0xmariowu/AgentLint@v1
```

This runs the default local-only core scan and does not fail the build on score thresholds. Add `fail-below` after the first passing run if you want a hard quality gate.

### SARIF integration

To get AgentLint findings in your repo's **Security tab** and as **inline PR annotations**, enable SARIF upload:

```yaml
permissions:
  contents: read
  security-events: write  # required for SARIF upload

steps:
  - uses: actions/checkout@v4
  - uses: 0xmariowu/AgentLint@v1
    with:
      sarif-upload: 'true'
```

> **Note:** SARIF upload requires Code scanning enabled (free for public repos, GHAS for private). Inline PR annotations via `::warning` commands work on all repos regardless.

### Platform requirements

The scanner is a bash script, so the host needs a POSIX shell:

| Platform | Requirement                                                                                                                                                                                                                                                                                                               |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| macOS    | Works out of the box (system bash).                                                                                                                                                                                                                                                                                       |
| Linux    | Works out of the box. `jq` and `git` must be on `PATH`.                                                                                                                                                                                                                                                                   |
| Windows  | Requires **Git Bash** (from [Git for Windows](https://git-scm.com/download/win)) or **WSL** ([install guide](https://learn.microsoft.com/windows/wsl/install)). Run `npx agentlint-ai` from inside the bash shell. Installing from `cmd.exe` or PowerShell will exit with a message pointing to one of those two options. |

Node.js 20+ is required on every platform.

## Supported AI coding agents

AgentLint auto-detects the entry file for major AI coding agents. Claude-specific checks skip gracefully for other platforms so they aren't penalized unfairly.

| Agent                 | Entry file                              | Notes                                                            |
| --------------------- | --------------------------------------- | ---------------------------------------------------------------- |
| Claude Code           | `CLAUDE.md`                             | Full check coverage including F7 @include and C5 CLAUDE.local.md |
| OpenAI Codex / Agents | `AGENTS.md`                             | Core checks apply                                                |
| Cursor                | `.cursorrules` or `.cursor/rules/*.mdc` | Core checks apply                                                |
| GitHub Copilot        | `.github/copilot-instructions.md`       | Core checks apply                                                |
| Google Gemini CLI     | `GEMINI.md`                             | Core checks apply                                                |
| Windsurf              | `.windsurfrules`                        | Core checks apply                                                |
| Cline                 | `.clinerules`                           | Core checks apply                                                |

If multiple entry files exist, priority order is CLAUDE.md → AGENTS.md → .cursorrules → copilot-instructions.md → GEMINI.md → .windsurfrules → .clinerules → .cursor/rules/\*.mdc. The winning file is reported in F1's measured\_value along with all detected files.

## 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          ██████████████████░░  9/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 HTML report shows a segmented gauge, expandable dimension breakdowns with per-check detail, and a prioritized issues list. Before/after comparison when fixes are applied.

## Why this matters

AI coding agents read your repo structure, docs, CI config, and handoff notes. They `git push`, trigger pipelines, and write files. A well-structured repo gets dramatically better AI output. A poorly structured one wastes tokens, ignores rules, repeats mistakes, and may expose secrets.

AgentLint is built on data most developers never see:

* **265 versions** of Anthropic's Claude Code system prompt — every word added, deleted, and rewritten
* **Claude Code internals** — hard limits (40K char max, 256KB file read limit, pre-commit hook behavior) that silently break your setup
* **Production security audits** across open-source codebases — the gaps AI agents walk into
* **4,533-repo corpus analysis** — hook/permission anti-patterns across 739 hooks and 1,562 settings.json files
* **6 academic papers** on instruction-following, context files, and documentation decay

## How scoring works

Each check produces a 0-1 score, weighted by dimension, scaled to 100. The total is averaged **only** over dimensions whose checks actually ran — dimensions with no evidence show `n/a`, not `0/10`, and don't drag the total down.

### Core dimensions (always run)

These 6 dimensions are evaluated by the deterministic scanner. They run in CLI, the GitHub Action, and Claude Code `/al` by default. The weights below sum to 100%.

| Dimension    | Weight | Why?                                                                  |
| ------------ | ------ | --------------------------------------------------------------------- |
| Instructions | 25%    | Unique value. No other tool checks CLAUDE.md quality                  |
| Findability  | 20%    | AI can't follow rules it can't find                                   |
| Workability  | 18%    | Can AI actually run your code?                                        |
| Safety       | 15%    | Is AI working without exposing secrets or triggering vulnerabilities? |
| Continuity   | 12%    | Does knowledge survive across sessions?                               |
| Harness      | 10%    | Are your Claude Code hooks/permissions actually configured correctly? |

Default total line: `Score: NN/100 (core)`.

### Extended dimensions (opt-in)

These two require runtime conditions that CI and a plain CLI can't provide: Deep needs an AI sub-agent, Session needs local Claude Code logs. They are opt-in via Claude Code `/al`. When they run, the total header shows `(core+extended)` and includes their contributions.

| Dimension | When it runs                           | What it adds                                                 |
| --------- | -------------------------------------- | ------------------------------------------------------------ |
| Deep      | `/al` with "AI Deep Analysis" selected | Contradictions, dead-weight rules, vague decision boundaries |
| Session   | `/al` with "Session Analysis" selected | Patterns from your Claude Code session logs                  |

Scores are measurements, not judgments. Reference values come from Anthropic's own data. You decide what to fix.

## Evidence

Every check cites its source. Full citations in [`standards/evidence.json`](https://github.com/0xmariowu/AgentLint/blob/main/standards/evidence.json).

| Source                                                                                                                      | Type                                 |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| [Anthropic 265 versions](https://cchistory.mariozechner.at)                                                                 | Primary dataset                      |
| [corpus-4533](https://github.com/0xmariowu/AgentLint/blob/main/standards/evidence.json) analysis of 4,533 Claude Code repos | First-party data                     |
| Claude Code internals                                                                                                       | Hard limits and observed behavior    |
| [IFScale](https://arxiv.org/abs/2507.11538) (NeurIPS)                                                                       | Instruction compliance at scale      |
| [ETH Zurich](https://arxiv.org/abs/2602.11988)                                                                              | Do context files help coding agents? |
| [Codified Context](https://arxiv.org/abs/2602.20478)                                                                        | Stale content as #1 failure mode     |
| [Agent READMEs](https://arxiv.org/abs/2511.12884)                                                                           | Concrete vs abstract effectiveness   |

## Requirements

* [Claude Code](https://claude.com/download)
* Node.js 20+
* `bash`, `jq`, `git` on `PATH` (macOS/Linux work out of the box; on Windows use **Git Bash** or **WSL** — see [Platform requirements](#platform-requirements) above)

## Update

```bash
npm install -g agentlint-ai
```