Lighthouse for AI Agents

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

54 Commits

54 Commits

.github/workflows

.github/workflows

bin

bin

docs

docs

src

src

test

test

.gitignore

.gitignore

.prettierrc

.prettierrc

CHANGELOG.md

CHANGELOG.md

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE

LICENSE

README.md

README.md

SECURITY.md

SECURITY.md

ax-logo.svg

ax-logo.svg

eslint.config.js

eslint.config.js

package-lock.json

package-lock.json

package.json

package.json

tsconfig.json

tsconfig.json

Repository files navigation

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

Apache 2.0

Built by Lucio Duran

About

Audit websites for AI Agent Experience (AX) readiness

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing

Security policy

Security policy

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases 22

v3.6.0 — AI licensing, cloaking detection, crawl efficiency & full documentation

Latest

Jun 9, 2026

+ 21 releases

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

TypeScript 56.4%

JavaScript 43.6%