botvisibility

v3.0.0

Published

3 months ago

Lighthouse for AI agents — scan any URL across 58 checks and 5 levels (Discoverable, Usable, Optimized, Indexable, Agent-Native), all run externally, to see how ready it is for Claude, GPT, and autonomous agent frameworks.

0High
0Medium
0Low

botvisibility

ai agents agent-native llm openapi llms.txt agent-card api scanner audit mcp webmcp x402 content-signals indexable seo ai-seo ai-search

BotVisibility CLI

Lighthouse for AI agents. Scan any URL to see how visible and usable it is to Claude, GPT, Copilot, and autonomous agent frameworks.

npx botvisibility stripe.com

Why this exists

When AI agents browse a site that doesn't publish machine-readable metadata or APIs, they fall back to scraping HTML, guessing endpoints, and retrying. That burns 5-100x more tokens per session and silently inflates the cost of every agent interaction. BotVisibility runs 58 automated checks across 5 levels — all run externally against a live URL — and tells you exactly what's missing and how to fix it.

Install & run

No install needed:

npx botvisibility <url>

Or globally:

npm install -g botvisibility
botvisibility stripe.com

Usage

# Basic URL scan
npx botvisibility https://example.com

# JSON output for CI/CD
npx botvisibility stripe.com --json

# Also scan a local project directory alongside the live URL (supplementary)
npx botvisibility https://myapp.com --repo ./

# Combined scan with JSON output
npx botvisibility mysite.com --repo ../my-backend --json

What it checks

Five levels, 58 total checks — all run externally against a live URL (no source access required for any level, including Level 5). The full reference lives in docs/checks.md. Quick overview:

Level 1 — Discoverable (18 checks): llms.txt, agent-card, OpenAPI spec, robots.txt AI policy, MCP server, ai.json, skill files, RSS, page token efficiency, content signals, API catalog (RFC 9727), markdown-for-agents, WebMCP, and more.
Level 2 — Usable (11 checks): API read/write/primary actions, API key auth, scoped keys, OIDC, structured errors, async ops, idempotency, OAuth protected-resource (RFC 9728), x402 payments.
Level 3 — Optimized (7 checks): sparse fields, cursor pagination, filtering, bulk ops, rate limit headers, caching headers, MCP tool quality.
Level 4 — Indexable (15 checks): Googlebot allowed, Google-Extended policy, homepage indexable, sitemap, HTTPS, viewport, JSON-LD, entity schema, canonical URL, heading hierarchy, image alt coverage, substantive content, structured data quality, entity coverage, content freshness.
Level 5 — Agent-Native (7 checks): intent endpoints, agent sessions, scoped agent tokens, audit logs, sandbox env, consequence labels, native tool schemas. Each passes only when the capability is declared (in /.well-known/agent-card.json, or OpenAPI for consequence labels) and the declared endpoint responds to a live probe.

--repo <path> is optional and supplementary: it scans a local project directory alongside the live URL to surface implementations that may not be published yet. It is not required for any check (including Level 5) and does not affect the score.

Scoring

BotVisibility uses a weighted cross-level algorithm so investing in higher-level capabilities still moves your score even if some low-level items are missing. Scan output matches the botvisibility.com web scan (scoringVersion, score, currentLevel, levels, checks) so CLI and web results are interchangeable. Full algorithm and worked examples in docs/scoring.md.

CI/CD integration

Drop into any CI to catch agent-readiness regressions:

- name: Check BotVisibility
  run: |
    SCORE=$(npx botvisibility mysite.com --json | jq '.currentLevel')
    if [ "$SCORE" -lt 1 ]; then
      echo "BotVisibility score below Level 1"
      exit 1
    fi

Recipes for GitHub Actions, GitLab CI, and CircleCI in docs/ci-integration.md.

The agent tax

Every unoptimized interaction costs AI agents extra tokens. At Claude Sonnet 4.6 rates and 1,000 agent visits per day, an unoptimized site can waste $22,800/month in tokens. Full analysis and methodology in docs/agent-tax.md.

Changelog

Release notes for every version live in CHANGELOG.md. Latest: 3.0.0 — Level 5 (Agent-Native) is now verified externally (declaration + live probe), so all 58 checks across all 5 levels run from a live URL scan with no --repo/source access. getCurrentLevel can now reach 5, Level 4 grew to 15 checks, scan output matches the web scan shape, and --repo is now optional/supplementary (breaking: cliChecks removed, --repo no longer required for Level 5).

Contributing

Contributions welcome. See CONTRIBUTING.md for development setup and how to add a new check.

License

MIT