agents-md-validator

CLI and TypeScript library for validating repository AGENTS.md files against the AGENTS.md Specification.

Usage

npm install
npx agents-validator validate .
npx agents-validator validate . --format yaml
npx agents-validator list-rules
npx agents-validator explain AGENTS301
npx agents-validator inspect .
npx agents-validator doctor .

Development

npm test
npm run typecheck
npm run build
npm run dogfood   # validate repo-root AGENTS.md (after build)

See STABILITY.md (semver contracts) and BROWSER.md (in-memory / bundler notes). Third-party rules: customRules + AGENTS9xx codes per specification.

Appendix — Token estimation (informative)

Every ValidationReport includes tokenEstimation: UTF-8 byte length, UTF-16 code-unit count, heuristic estimatedTokens = ceil(utf8ByteLength / 4), literal estimationMethod, a nominal 128 000-token reference for estimatedContextSharePercent only, and no effect on conformance or score. See AGENTS.md Specification — Appendix C §C.22.

API

import { validateAgentsMd, validateAgentsMdString } from "agents-md-validator";

const report = await validateAgentsMd({ rootDir: process.cwd() });
const fromPaste = validateAgentsMdString("---\nagents: {}\n---\n\n# Hi\n");