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
███████████████████████████████████░░░░░ 88/100 Good
LLMs.txt (100/100)
PASS /llms.txt exists
PASS /llms.txt Content-Type OK (text/plain)
PASS H1 heading: "Lucio Duran — Personal Portfolio"
Robots.txt (100/100)
PASS All 8 core AI crawlers explicitly configured
PASS Content signals declared for User-agent: * — search=yes, ai-train=no
Content Negotiation (100/100)
PASS Homepage serves Markdown via content negotiation (Accept: text/markdown)
PASS Markdown is ~95% lighter than the HTML representation
...
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 — discovery files, crawler policy, licensing, content negotiation, and the failure modes invisible to operators (like a WAF blocking crawlers your robots.txt allows).
What it checks
18 checks — 14 weighted, 4 informational. Full reference: docs/checks.md.
| Check | Weight | Check | Weight |
|---|---|---|---|
| LLMs.txt | 11% | Security.txt | 6% |
| Robots.txt + Content Signals | 11% | Meta Tags (OG / Twitter / AI) | 6% |
| HTML Rendering | 9% | OpenAPI | 6% |
| Structured Data (JSON-LD) | 9% | TLS / HTTPS | 5% |
| HTTP Headers | 9% | Sitemap | 4% |
| Agent Card (A2A) | 7% | AI Well-Known | 3% |
| MCP | 7% | Content Negotiation (Markdown for Agents) | 0%* |
| SEO Basics | 7% | RSL License · Agent Access (cloaking) · Crawl Efficiency | 0%* |
* Informational in 3.x: reported in full, no effect on the score. Weighted in v4.0.
Every finding links to a step-by-step remediation guide.
Usage
ax-audit https://example.com # full audit, terminal output ax-audit https://a.com https://b.com --concurrency 2 # batch, in parallel ax-audit https://example.com --output markdown # also: json, html ax-audit https://example.com --checks llms-txt,rsl # subset of checks ax-audit https://example.com --only-failures # hide passing findings ax-audit https://example.com --baseline .ax-baseline.json --fail-on-regression 5
Exit codes gate CI: 0 for score ≥ 70, 1 below. Full flag reference: docs/cli.md · CI recipes (PR comments, regression gates, scheduled audits): docs/ci.md.
Programmatic API
import { audit, batchAudit } from 'ax-audit'; const report = await audit({ url: 'https://example.com' }); report.overallScore; // 0–100 report.results; // per-check findings
Full API and types: docs/api.md.
Documentation
Start here:
| Document | Contents |
|---|---|
| docs/getting-started.md | First audit, reading the report, fixing in impact order |
| docs/concepts.md | The AX standards landscape — llms.txt, A2A, MCP, RSL, Content Signals, Web Bot Auth |
Reference:
| Document | Contents |
|---|---|
| docs/checks.md | All 18 checks with exact scoring per finding, weights, scoring model |
| docs/cli.md | Every flag, output formats, exit codes, baseline workflow |
| docs/api.md | audit, batchAudit, baselines, reporters, types, API-stability policy |
| docs/ci.md | GitHub Actions recipes: gates, PR comments, scheduled drift detection |
| docs/architecture.md | Pipeline design, check anatomy, how to add a check, scoring policy |
| docs/faq.md | Troubleshooting, false positives, the agent-access verified-bots caveat |
| Remediation guides | Step-by-step fixes for every finding |
The same documentation is browsable at lucioduran.com/projects/ax-audit/docs, rendered from these files. Contributors: see CONTRIBUTING.md and SECURITY.md.
Scoring
| Grade | Score | Exit Code |
|---|---|---|
| Excellent | 90–100 | 0 |
| Good | 70–89 | 0 |
| Fair | 50–69 | 1 |
| Poor | 0–49 | 1 |
Tech
TypeScript strict mode · 2 runtime dependencies (chalk, commander) · Node 18+ built-in fetch · parallel checks via Promise.allSettled · per-run request cache with Vary-aware keys · transient-failure retries with backoff · 301 tests on node:test with zero test dependencies.
Contributing
Contributions are welcome — see docs/architecture.md for the pipeline design, check anatomy, and the steps (code, tests, docs, remediation guide) a new check requires.
Related
- ax-init — generate the AX files this tool audits
- ax-cite — embed AI-extractable structured data in your pages
License
Built by Lucio Duran