Llmscout

LLMScout

Install • Quickstart • CLI reference • Comparison • FAQ • Contributing

Runs 21 technical-SEO and GEO (generative-engine-optimization) checks against your site, in pure TypeScript or pure Python, with zero Python interpreter, zero headless browser, and zero external toolchain either way.

Install

LLMScout ships as two independent, complementary distributions. Both run the same 21 checks with the same PASS/WARN/FAIL verdicts, so pick whichever fits your toolchain.

Node/TypeScript (npm):

npm install -g llmscout-cli

llmscout init ./my-site --site-url https://example.com llmscout check ./my-site

The CLI targets Node 18+ (declared in package.json engines). The two runtime dependencies are cheerio (HTML parsing) and commander (argument parsing): there is no Python interpreter, no pip install, and no Playwright/Chromium download anywhere in the npm install.

[!NOTE]

The npm install pulls in undici as a transitive dependency of cheerio. npm audit has flagged a high-severity advisory against it in the past; package.json's overrides block pins undici (and js-yaml/nanoid) to patched ranges to close it. Run npm audit after install to confirm your resolved tree is clean.

Python (PyPI):

pip install llmscout-cli

llmscout init ./my-site --site-url https://example.com llmscout check ./my-site

Zero runtime dependencies -- HTML parsing and HTTP fetching both use only the Python standard library. See python/README.md for the full Python-specific guide.

Then, in any project you want to check:

llmscout init .

That scaffolds a llmscout.json config and a small Claude Code skill file into the target directory. Set your site URL and run llmscout check ..

Quickstart

Scaffold a config and run a check against a live site:

llmscout init ./my-site --site-url https://example.com

llmscout check ./my-site

Real output from llmscout check against https://example.com:

LLMScout check -- https://example.com

[PASS] (technical) Title tag Title "Example Domain" is 14 characters, within the recommended 10-60 range.

[WARN] (technical) Meta description No meta description found. Fix: Add with 50-160 characters summarizing the page.

[WARN] (technical) Canonical tag No tag found. Fix: Add a canonical link tag pointing at the preferred URL for this page.

[FAIL] (technical) robots.txt robots.txt was not reachable at https://example.com/robots.txt (HTTP 404). Fix: Add a robots.txt file at your site root, even a permissive one, so crawlers and agents have explicit directives.

[WARN] (technical) sitemap.xml No sitemap was reachable (tried: https://example.com/sitemap.xml). Fix: Add a sitemap.xml at your site root, or point to one with a Sitemap: directive in robots.txt, to help search engines discover pages.

[PASS] (technical) Heading structure Exactly one and no skipped heading levels detected.

[PASS] (technical) Image alt coverage No tags found on the page.

[WARN] (technical) Open Graph tags No Open Graph tags found. Fix: Add Open Graph meta tags (og:title, og:description, og:image, og:url) so shared links render rich previews on social platforms.

[WARN] (technical) Twitter/X Card tags No twitter:card meta tag found. Fix: Add (or another valid card type) so links render rich previews on X/Twitter.

[WARN] (technical) Meta robots directives No meta robots directives found; default Google Search snippet/preview limits will apply. Fix: Add to control search snippet appearance.

[PASS] (technical) Image weight No tags with an http(s) src to measure.

[PASS] (technical) Redirect chain The homepage resolved with no redirects.

[WARN] (geo) Structured data (JSON-LD) No JSON-LD structured data found. Fix: Add schema.org JSON-LD markup (e.g. Organization, WebSite, or Article) so generative engines can understand the page's entities.

[WARN] (geo) llms.txt No llms.txt found at https://example.com/llms.txt. Fix: Optional: add an llms.txt at your site root summarizing the site for LLM-based agents (see llmstxt.org).

[WARN] (geo) AI crawler directives robots.txt is unreachable, so AI-crawler directives could not be determined. Fix: Add a reachable robots.txt if you want to state an explicit policy for AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, Claude-SearchBot, PerplexityBot, Google-Extended, Applebot-Extended).

[WARN] (geo) FAQ schema No FAQPage structured data found. Fix: If this page has an FAQ section, mark it up with FAQPage JSON-LD so generative engines can surface individual answers.

[PASS] (geo) Content extraction friendliness Found 1 heading(s) and 1 structured text block(s); content appears reasonably extractable. (Heuristic: cannot assess semantic quality or JS-rendered content.)

[WARN] (geo) Speakable schema No Speakable structured data found. Fix: If this page has content suited for voice assistants, add a "speakable" SpeakableSpecification to its JSON-LD so voice search can surface it.

[WARN] (geo) Organization schema No Organization/Corporation/LocalBusiness/Person structured data found. Fix: Add Organization (or Person) JSON-LD with a sameAs array of your official social/profile URLs to strengthen Knowledge Panel signals.

[WARN] (geo) Markdown content negotiation Requesting https://example.com/ with "Accept: text/markdown" returned Content-Type "text/html" instead of text/markdown. Fix: Optional: serve a text/markdown representation of pages when the client sends "Accept: text/markdown" so LLM-based agents can fetch clean Markdown directly instead of parsing HTML.

[WARN] (geo) Link header (RFC 8288) The homepage does not send a Link response header. Fix: Optional: add an RFC 8288 Link response header (e.g. https://example.com/feed; rel="alternate") to advertise machine-readable service-discovery endpoints to crawlers and AI agents.

Summary: 6 PASS, 14 WARN, 1 FAIL (21 checks)

The same run with --json:

llmscout --json check ./my-site

{

"siteUrl": "https://example.com", "summary": { "pass": 6, "warn": 14, "fail": 1, "total": 21 }, "results": [ { "id": "title", "name": "Title tag", "category": "technical", "status": "PASS", "message": "Title \"Example Domain\" is 14 characters, within the recommended 10-60 range." } ] }

check exits 0 when no check FAILs, 1 when at least one check FAILs (WARN alone does not fail the run), and 2 on a usage error such as a missing or misconfigured llmscout.json.

Features

• 21 checks across two categories. 12 technical-SEO checks and 9 GEO checks, listed by name in The 21 checks.
• Zero external toolchain, either language. child_process is never imported anywhere in the TypeScript source; the Python port has zero runtime dependencies. Checks run inside the process instead of shelling out to Python scripts or a headless browser.
• Cross-platform by construction. No python3-versus-py -3 shelling and no relative-path script resolution, so the same install runs identically on Windows, macOS, and Linux.
• Hardened fetch. The single fetch wrapper (src/fetch-utils.ts) rejects any non-http(s) scheme, blocks loopback/private/link-local hosts, follows redirects manually one hop at a time, and bounds the chain at 5 hops and the response body at 10 MiB.
• Fleet mode with per-site reports. llmscout fleet manifest.json runs the full suite across many local client-repo paths in one invocation, and --out-dir writes one auto-named report file per site -- built for agencies checking many client sites at once.
• Structured output. Every command accepts a global --json flag for machine-readable output, so an agent invoking the CLI can parse results programmatically.
• A real, configurable User-Agent. Sends a genuine browser User-Agent by default (some SSR frameworks and CDNs reject bot-style strings outright) and a --user-agent flag to override it.
• Well tested. 248 TypeScript tests and 233 Python tests, both reproducible locally with npm test / npm run test:coverage and pytest. The Python distribution has zero runtime dependencies, so there is nothing for a dependency audit to flag. On the npm side, package.json's overrides block pins undici (a transitive dependency of cheerio) to a patched range, and npm audit currently reports zero vulnerabilities.

Why GEO checks matter right now

Search traffic is genuinely shifting toward AI-mediated answers, and the shift is recent and well measured, not a hypothetical:

• Google's own AI Overviews are already cutting click-through. Ahrefs measured position-1 CTR on AI-Overview-triggering keywords fall from 7.3% (December 2023) to 1.6% (December 2025) -- a 58% average CTR reduction across the study. (Ahrefs, December 2025) Semrush's independent 10-million-keyword analysis found organic CTR drops 61% and paid CTR drops 68% when an AI Overview appears on the results page. (Semrush)
• ChatGPT itself is now a real, measurable traffic source. Search Engine Land's analysis of 6.77 million sessions found ChatGPT accounts for 92% of all AI-assistant referral traffic, converting at 7.1% -- close to paid search's 7.8%. (Search Engine Land)
• AI crawlers are not one crawler anymore. Between May 2024 and May 2025, GPTBot's share of AI-crawler traffic rose from 5% to 30%. OpenAI and Anthropic have since split their bots into training crawlers (GPTBot, ClaudeBot) and separate, independently blockable search/retrieval crawlers (OAI-SearchBot, Claude-SearchBot). (Cloudflare Radar, "From Googlebot to GPTBot") LLMScout's ai-crawler-directives check reports on all seven of the current major training and search bots (GPTBot, OAI-SearchBot, ClaudeBot, Claude-SearchBot, PerplexityBot, Google-Extended, Applebot-Extended) separately, since blocking a company's training bot has no effect on whether its assistant can still retrieve and cite your page live through its own search bot.
• **Markdown-native delivery is a real, emerging practice, not