agents-audit CLI

1. Quick Start

Run the audit tool against any repository:

npx agents-audit

This produces a hygiene report for your AGENTS.md file (and agents.workspace.json, if present). No installation required. No account, no telemetry, no signup.

The tool exits with code 0 by default; use --fail-on=<severity> to gate CI builds on findings.

2. What It Does

agents-audit reads AGENTS.md (and optionally agents.workspace.json), walks the repository, and produces hygiene findings with a composite score. Findings identify mismatches between what AGENTS.md describes and what is actually present in the repository: stale file references, misconfigured framework entries, convention drift, and similar issues that accumulate as codebases evolve.

3. Installation

3.1 npx (Recommended for One-Off Use)

npx agents-audit

No installation. Always runs the latest version.

3.2 Global Install

npm install -g agents-audit
agents-audit

3.3 GitHub Action

- name: Audit AGENTS.md
  run: npx agents-audit --fail-on=error --json > agents-audit-report.json

4. Usage

4.1 Default Invocation

npx agents-audit

Reads AGENTS.md and agents.workspace.json from the current directory. Produces terminal output with findings grouped by severity.

4.2 Saving Reports

npx agents-audit --save

Writes a Markdown report to .agents/audit-report.md.

4.3 CI Integration

# Fail on error-severity findings
npx agents-audit --fail-on=error

# Machine-readable JSON output for downstream processing
npx agents-audit --json

# Combined: fail on errors, save JSON for CI artifact
npx agents-audit --fail-on=error --json > audit.json

4.4 Verbosity Flags

# Suppress all output except the exit code
npx agents-audit --quiet

# Full detail for each finding
npx agents-audit --verbose

5. Output Formats

5.1 Terminal Output

The default terminal output groups findings by severity:

agents-audit v0.3.0

✗ ERROR  missing-file-reference (3 findings)
✗ WARN   framework-drift (1 finding)
✓ PASS   pattern-zero-match
✓ PASS   section-staleness
✓ PASS   convention-mismatch

Score: 74/100

Run with --verbose for finding details.

5.2 Markdown Report

Generated by --save. Written to .agents/audit-report.md. Suitable for committing or sharing as a CI artifact.

5.3 JSON Output

Generated by --json. Machine-readable array of finding objects:

[
  {
    "rule": "missing-file-reference",
    "severity": "error",
    "file": "AGENTS.md",
    "line": 47,
    "message": "AGENTS.md line 47 references `src/auth/middleware.ts` which does not exist",
    "remediation": "Update the reference to the current file location or restore the file"
  }
]

6. The Hygiene Score

6.1 What It Means

The hygiene score (0–100) reflects how well AGENTS.md describes the current state of the repository. A score of 100 means no findings. Each finding deducts points based on its severity and rule weight.

6.2 How It’s Calculated

Errors deduct more points than warnings. Rule weights are defined in @workspacejson/rules and can be inspected via:

npx agents-audit --explain-score

6.3 What a Healthy Score Looks Like

• 90–100: Healthy. AGENTS.md accurately reflects the repo.
• 70–89: Minor drift. Common in fast-moving codebases. Address warnings when convenient.
• 50–69: Notable drift. Agents reading AGENTS.md may receive stale context. Remediate errors first.
• < 50: Significant drift. Prioritize remediation before running AI sessions on this codebase.

7. The Five Rules

missing-file-reference

Severity: error
Category: integrity

Detects when AGENTS.md mentions a file path that does not exist in the repository.

Example finding:

AGENTS.md line 47 references `src/auth/middleware.ts`
This file does not exist in the repo (last seen: 14 days ago)
Remediation: Update AGENTS.md to reference the current auth
file location, or restore the referenced file.

pattern-zero-match

Severity: warning
Category: accuracy

Detects when a glob pattern in AGENTS.md matches zero files. Patterns that never match are likely stale or misconfigured.

Example finding:

AGENTS.md pattern `apps/*/src/**/*.service.ts` matches 0 files
Remediation: Verify the pattern is correct for your directory
structure, or remove it if the service pattern no longer applies.

framework-drift

Severity: warning
Category: accuracy

Detects when the framework versions in agents.workspace.json differ from the versions installed in package.json / requirements.txt.

Example finding:

agents.workspace.json records Next.js 14.2.0, but package.json has 15.3.1
Remediation: Regenerate agents.workspace.json with agents-audit or your
agents.workspace.json generator.

section-staleness

Severity: warning
Category: freshness

Detects when AGENTS.md sections reference content that has not been updated recently relative to the files they describe.

Example finding:

AGENTS.md "Database conventions" section references 4 files
The most recently modified of those files is 180 days old
The section content was last updated 210 days ago
Remediation: Review the section for accuracy and update its
timestamp comment if the content is still current.

convention-mismatch

Severity: warning
Category: accuracy

Detects when coding conventions stated in AGENTS.md conflict with observed patterns in the codebase.

Example finding:

AGENTS.md states: "Use named exports: no default exports"
Observed: 12 files use default exports (src/components/*.tsx)
Remediation: Update the convention statement to match current
practice, or fix the files to follow the stated convention.

8. Configuration

8.1 .agentsauditrc

Place .agentsauditrc at the repository root to configure agents-audit:

{
  "failOn": "error",
  "saveReport": true,
  "reportPath": ".agents/audit-report.md"
}

8.2 Per-Rule Overrides

{
  "rules": {
    "section-staleness": {
      "level": "off"
    },
    "missing-file-reference": {
      "level": "error"
    }
  }
}

8.3 Ignore Patterns

{
  "ignore": [
    "docs/**",
    "*.generated.ts"
  ]
}

9. FAQ-Lite

Why no telemetry by default?

agents-audit runs entirely locally. It does not make network requests during auditing. There is no telemetry, crash reporting, or anonymous usage data collection by default.

How is this different from ESLint?

ESLint audits code syntax and style. agents-audit audits the relationship between your agent context documentation (AGENTS.md, agents.workspace.json) and the current state of your codebase. They serve different purposes and are not substitutes for each other.

Does it work without agents.workspace.json?

Yes. agents-audit audits AGENTS.md alone when agents.workspace.json is not present. The framework-drift rule is skipped when agents.workspace.json is absent, and other rules use filesystem inspection rather than agents.workspace.json data.