ax-audit

Lighthouse for AI Agents. Audit any website's AI Agent Experience (AX) readiness in seconds.

npx ax-audit https://your-site.com

  AX Audit Report
  https://lucioduran.com

  ███████████████████████████████████████░  98/100  Excellent

  LLMs.txt (100/100)
    PASS  /llms.txt exists
    PASS  H1 heading: "Lucio Duran — Personal Portfolio"
    PASS  /llms-full.txt also available (bonus)

  Robots.txt (100/100)
    PASS  All 6 core AI crawlers explicitly configured
    PASS  31/31 known AI crawlers have explicit rules
  ...

Why

AI agents and LLMs are increasingly crawling, indexing, and interacting with websites. Just like Lighthouse audits web performance and axe-core audits accessibility, ax-audit tells you how ready your site is for the AI agent ecosystem.

What it checks

| Check | What it audits | Weight | |---|---|---| | LLMs.txt | /llms.txt presence and llmstxt.org spec compliance | 15% | | Robots.txt | AI crawler configuration, wildcard detection, partial path restrictions | 15% | | Structured Data | JSON-LD on homepage (schema.org, @graph, entity types) | 13% | | HTTP Headers | Security headers + AI discovery Link headers + CORS on .well-known | 13% | | Agent Card | /.well-known/agent.json A2A protocol compliance | 10% | | MCP | /.well-known/mcp.json Model Context Protocol server config | 10% | | Security.txt | /.well-known/security.txt RFC 9116 compliance | 8% | | Meta Tags | AI meta tags (ai:*), rel="alternate" to llms.txt, rel="me" identity links | 8% | | OpenAPI | /.well-known/openapi.json presence and schema validity | 8% |

Install

npm install -g ax-audit

Or run directly without installing:

npx ax-audit https://your-site.com

Usage

# Full audit with colored terminal output
ax-audit https://example.com

# Batch audit — audit multiple URLs in a single run
ax-audit https://example.com https://other-site.com https://third.dev

# HTML report — self-contained, dark mode, shareable
ax-audit https://example.com --output html > report.html

# JSON output for CI/CD pipelines
ax-audit https://example.com --json

# Run only specific checks (validates IDs, errors on unknown)
ax-audit https://example.com --checks llms-txt,robots-txt,agent-json

# Custom timeout per request (default: 10s)
ax-audit https://example.com --timeout 15000

# Verbose mode — see every HTTP request, cache hit, and check score
ax-audit https://example.com --verbose

# Only show failures and warnings (hide passing findings)
ax-audit https://example.com --only-failures

Batch Mode

Pass multiple URLs to audit them sequentially. Each gets its own full report, followed by a summary table:

  ═══ Batch Summary ═══

  URL                                     Score       Grade
  ────────────────────────────────────────────────────────────
  https://example.com                     92/100    Excellent
  https://other-site.com                  45/100         Poor

  2 URLs audited: 1 passed, 1 failed
  ████████████████████████████░░░░░░░░░░░░  69/100 avg  Fair

Exit code: 0 if all URLs score >= 70, 1 if any fails.

HTML Report

Generate a self-contained HTML report you can open in any browser or share with your team:

ax-audit https://example.com --output html > report.html

Features: circular score gauge, dark/light mode, collapsible check sections, responsive design. Works for both single and batch audits.

Programmatic API

Full TypeScript support with all types exported.

import { audit, batchAudit } from 'ax-audit';
import type { AuditReport, BatchAuditReport } from 'ax-audit';

// Single URL
const report: AuditReport = await audit({ url: 'https://example.com' });
console.log(report.overallScore); // 0-100
console.log(report.grade.label);  // 'Excellent' | 'Good' | 'Fair' | 'Poor'
console.log(report.results);      // Individual check results with findings

// Batch audit
const batch: BatchAuditReport = await batchAudit(
  ['https://example.com', 'https://other.com'],
  { timeout: 10000 }
);
console.log(batch.summary.averageScore); // Average across all URLs
console.log(batch.summary.passed);       // Number of URLs scoring >= 70

Also exports calculateOverallScore, getGrade, and checks for advanced usage.

Scoring

Each check returns a score from 0 to 100. The overall score is a weighted average across all checks.

| Grade | Score | Exit Code | |---|---|---| | Excellent | 90 - 100 | 0 | | Good | 70 - 89 | 0 | | Fair | 50 - 69 | 1 | | Poor | 0 - 49 | 1 |

Exit codes make it easy to gate CI/CD deployments on AX readiness.

CI Integration

GitHub Actions

- name: AX Audit
  run: npx ax-audit https://your-site.com
  # Fails the step if score < 70

Save the report as an artifact:

- name: AX Audit (JSON)
  run: npx ax-audit https://your-site.com --json > ax-report.json

- uses: actions/upload-artifact@v4
  with:
    name: ax-audit-report
    path: ax-report.json

Available Checks

| Check ID | Use with --checks | |---|---| | llms-txt | LLMs.txt spec compliance | | robots-txt | AI crawler configuration | | structured-data | JSON-LD structured data | | http-headers | Security + AI discovery headers | | agent-json | A2A Agent Card | | mcp | MCP server configuration | | security-txt | RFC 9116 Security.txt | | meta-tags | AI meta tags and identity links | | openapi | OpenAPI specification |

Testing

npm test

97 tests covering all 9 checks, the scorer, and edge cases. Uses Node.js built-in test runner (node:test), no extra test dependencies.

Tech Stack

• TypeScript with strict mode
• 2 runtime dependencies: chalk + commander
• Node.js 18+ built-in fetch (zero HTTP libraries)
• Parallel check execution via Promise.allSettled
• In-memory request caching per audit run

Contributing

Contributions are welcome. To add a new check:

1. Create src/checks/your-check.ts exporting default (async check function) and meta (CheckMeta)
2. Use buildResult(meta, score, findings, start) from ./utils.js to return results
3. Register it in src/checks/index.ts
4. Add its weight to CHECK_WEIGHTS in src/constants.ts

License

Apache 2.0

Built by Lucio Duran