agenteval

# agenteval

Your CLAUDE.md is untested. So is your AGENTS.md, your cursor-instructions.md, and your .cursorrules.

agenteval is a linter, benchmarker, and CI gate for AI coding instructions. It finds dead references, token bloat, contradictions, and stale instructions before your agent does. Then it scores agent performance so you can measure whether your instruction changes actually help.

[![CI](https://github.com/lukasmetzler/agenteval/actions/workflows/ci.yml/badge.svg)](https://github.com/lukasmetzler/agenteval/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/agenteval-cli?label=npm)](https://www.npmjs.com/package/agenteval-cli)
[![npm downloads](https://img.shields.io/npm/dm/agenteval-cli)](https://www.npmjs.com/package/agenteval-cli)
[![Version](https://img.shields.io/github/v/release/lukasmetzler/agenteval?label=release)](https://github.com/lukasmetzler/agenteval/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

![agenteval demo](demo/demo.gif)

## Install

```bash
npm install -g agenteval-cli
```

Or pick your preferred method:

```bash
brew tap lukasmetzler/agenteval && brew install agenteval   # Homebrew
curl -fsSL https://raw.githubusercontent.com/lukasmetzler/agenteval/main/install.sh | bash  # Shell
```

No Bun, no Node at runtime. The binary is self-contained.

## Quick Start

```bash
agenteval lint                    # Find problems in your instruction files
agenteval lint --explain          # Same, with explanations for each rule
agenteval harvest --dry-run       # Preview what AI commits are in your history
agenteval ci                      # Run all tasks, fail on regressions
```

## What It Catches

- Dead references to files, paths, and headings that don't exist
- Filler phrases that waste context tokens ("make sure to", "it is important that")
- Contradictions between instruction files ("always use X" and "never use X")
- Content overlap and duplication across files
- Token budget overruns