OpenAEO Audit

Check whether your website is retrievable and citable by AI answer engines — ChatGPT, Claude, Gemini, and Perplexity — from your terminal, in one command.

npx openaeo-audit yoursite.com

No install, no signup, no dependencies. It fetches your page the way an AI crawler does, scores it out of 100, and hands you the exact fixes that raise it.

AEO (Answer Engine Optimization) and GEO (Generative Engine Optimization) are the new SEO: your customers increasingly ask an assistant instead of scrolling ten blue links, and the winners are whoever the AI can read, trust, and recommend. This tool tells you where you stand.

Quick start

# pretty report
npx openaeo-audit example.com

# machine-readable JSON (for CI, dashboards, scripts)
npx openaeo-audit example.com --json

Example output:

  example.com
  54/100  ·  AI-ready
  AI-ready, not yet cited.
  Retrievable, but thin on quotable specifics and structured data. Fixable without a redesign.

  ✓ Content readable in raw HTML  — 1,240 visible words
  ✗ robots.txt allows GPTBot, ClaudeBot, PerplexityBot  — robots.txt disallows gptbot
  ✗ llms.txt index present  — missing
  ⚠ Organization + WebSite JSON-LD  — Organization
  ⚠ Product / Offer schema with price  — no priced Offer
  ⚠ Answer + a number in the first 100 words  — vague / no title or meta
  ✗ FAQPage schema present  — missing
  ✓ Freshness (dateModified) present  — dateModified set

  6 fixes to raise your score:
  1. Unblock AI crawlers in robots.txt
     Why:  A single inherited Disallow line can hide you from ChatGPT and Perplexity entirely.
     How:  Explicitly Allow GPTBot, OAI-SearchBot, ClaudeBot, ... and link your sitemap.
  ...

What it checks

The audit runs the checks that most often decide whether an AI assistant can quote you:

Scoring

Each check scores pass (1.0), warn (0.4), or fail (0.0), averaged to a 0–100 score, then placed in a band:

Some failures cap the score no matter what else passes, because they block retrieval entirely:

• Content invisible without JavaScript → capped at 25
• Bot blocked at the edge (4xx/403) → capped at 25
• robots.txt disallows AI bots → capped at 40

An honest low score you can act on beats a flattering one that hides the real problem.

Use it as a library

const { audit, remediationPlan } = require("openaeo-audit");

const result = await audit("example.com");
console.log(result.score, result.band);      // 54 "AI-ready"

const fixes = remediationPlan(result);        // ordered, highest-leverage first
fixes.forEach(f => console.log(f.title));

audit(url) returns:

{
  "domain": "example.com",
  "score": 54,
  "band": "AI-ready",
  "verdict": "AI-ready, not yet cited.",
  "sub": "Retrievable, but thin on quotable specifics ...",
  "fixCount": 2,
  "edgeOk": true,
  "bots": [ { "name": "GPTBot", "surface": "ChatGPT", "kind": "fetched", "status": 200, "ok": true }, ... ],
  "checks": [ { "label": "...", "status": "pass|warn|fail", "detail": "..." }, ... ]
}

In CI

Fail a build if your score drops below a threshold:

score=$(npx openaeo-audit yoursite.com --json | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).score))")
[ "$score" -ge 65 ] || { echo "AEO score $score below 65"; exit 1; }

Use it from Cursor or Claude Code (MCP)

OpenAEO ships an MCP server, so your AI coding agent can audit your site and apply the fixes to your actual files — with you reviewing every edit. Nothing is uploaded, no account needed, and it never touches production.

Cursor — add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "openaeo": { "command": "npx", "args": ["-y", "openaeo-audit", "mcp"] }
  }
}

Claude Code / Claude Cowork — run this in your project:

claude mcp add openaeo -- npx -y openaeo-audit mcp

…or copy examples/.mcp.json to your project root.

For a repeatable workflow, drop examples/aeo-fix-pass/ into .claude/skills/ — then /aeo-fix-pass runs the whole audit-fix-verify pass, including the guardrails (merge robots.txt rather than overwrite, never invent numbers for the placeholders).

Then just ask:

"Audit example.com and fix my site."

The agent will run the audit, write robots.txt and llms.txt, inject the JSON-LD into your <head>, and re-check its work.

Not a developer? You only need your web address.

If your site is on Squarespace, Wix, Webflow, WordPress, Shopify, Framer, Ghost or Carrd, you don't have files to edit — so ask instead:

"My website is remyfilm.co — help me show up in AI search."

OpenAEO detects which platform you're on and replies with click-by-click steps for your admin ("Settings → Advanced → Code Injection → paste this in the Header"), plus the exact text to copy. It'll also tell you honestly when your platform can't do something, so you don't hunt for a setting that doesn't exist.

Tools it exposes

Hosted tools. These five call openaeo.dev and need OPENAEO_API_KEY, because they cannot run locally: citation testing needs provider keys for six assistants, and crawler intelligence reads a corpus collected across every audit anyone runs. Without a key they explain what they need rather than failing; the six tools above are unaffected.

Requirements

• Node.js 18+ (uses the built-in fetch)
• Zero npm dependencies

What this is — and isn't

What's in this repo. The audit engine: 5 retrieval gates, 8 headline checks, and a per-bot edge matrix that fetches your site as 8 named AI crawlers and records the HTTP status each one is given, plus the generators for robots.txt, llms.txt and JSON-LD, the CLI and the MCP server. Free forever, MIT, no account, no telemetry. It's the same engine that powers the free tier at openaeo.dev.

What isn't. The hosted service: the full 49-check weighted rubric tracked over time, weekly citation testing across six assistant surfaces, drift alerts, competitor share-of-voice, and audit history. That runs on our infrastructure, not yours.

The split is not about withholding the good part. Fixing a site is mostly a one-time job, and everything you need for it is here. Whether an assistant names you changes every week, and that is a thing that has to keep running whether or not anyone is watching. Sell the service, not the permission.

If the CLI is useful, the hosted version is the next step. Both tell you the truth; the hosted one keeps telling you over time.

Contributing

Issues and PRs welcome — especially new checks, better detection heuristics, and fixes for edge cases in how frameworks render. Keep the engine dependency-free.

License

MIT © OpenAEO. Use it, fork it, build on it.

Trademark

"OpenAEO" and the OpenAEO logo are trademarks of OpenAEO and are not licensed under the MIT License. Forks and derivative works may use this code freely, but must not use the OpenAEO name or logo in a way that suggests endorsement, affiliation, or that they are the official OpenAEO product or service.