Herdr LLM Lint — AI skill for Claude Code

herdr-llm-lint

Lints CLAUDE.md, AGENTS.md, and other agent instruction files for stale paths, commands, facts, and drift. Runs as a CLI and as a [Herdr](https://herdr.dev) plugin. Rust, one binary. Findings look like compiler output and carry a file and line. Covers `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, and nested `CLAUDE.md` and `AGENTS.md`.

Instruction files rot. A path moves, a Makefile target is renamed, a rule gets pasted into three files and edited in one. The agent reads the stale version every session and nobody notices until it does something wrong.

The design is in [docs/PLAN.md](docs/PLAN.md).

Install

herdr plugin install shindakun/herdr-llm-lint

Needs `cargo`; the install step builds the binary. Linux and macOS.

For local development, link the checkout instead:

cargo build --release
herdr plugin link /path/to/herdr-llm-lint

Use it

herdr-llm-lint lint                      # the nearest git root, text output
herdr-llm-lint lint path/to/repo
herdr-llm-lint lint --format json
herdr-llm-lint lint --fail-on error      # exit 1 only on errors

Output:

CLAUDE.md:7: ref-path: `internal/httpx/` does not exist
CLAUDE.md:9: ref-target: `make check` is not a Makefile target (have: build lint test)
CLAUDE.md:11: ref-command: `frobnicate` is not on PATH
CLAUDE.md: size-bytes: 9400 bytes, budget is 8192

Exit 1 when any finding is at or above `--fail-on` (default `warn`, so any finding).

`--fix` applies the safe subset, prints each action to stderr, then lints again and prints what remains:

• long lines reported by shape-lines or shape-body are wrapped at line_chars, with a list item's continuation indented under its text and backtick spans kept whole; headings are left alone
• a line reported by content-dup is dropped when it is an exact repeat (after trimming) of an earlier line; near-duplicates stay
• in each directory, an