geo-optimizer-skill

Open-source GEO audit engine for AI search visibility and citability.

GEO Optimizer helps you audit whether a website can be crawled, understood, cited, and monitored by AI answer engines.

Quick Start · Live Demo · Pricing · Sign Up · Documentation · Changelog

Why this exists

AI search engines give direct answers and cite their sources. If your site isn't optimized, you're invisible — even if you rank #1 on Google.

User: "What's the best mortgage calculator?"

Perplexity: "According to [Competitor.com], the formula is..."
             ↑ They appear. You don't.

GEO Optimizer audits your site against 47 research-backed methods (Princeton KDD 2024, AutoGEO ICLR 2026) and generates the fixes.

Why this matters in 2026

• ChatGPT alone serves 900M weekly users — a growing share of sessions that used to be Google searches.
• 28.3% of ChatGPT's most-cited pages have zero organic visibility on Google (Ahrefs) — AI engines reward different signals than classic SEO.
• Proper JSON-LD schema lifts LLM extraction accuracy from 16% to 54% (Semrush test on GPT-4).
• 844,000+ sites already ship an llms.txt. Yours?

GEO is not traditional SEO

SEO and GEO answer different questions:

• SEO optimizes for ranking and visibility in traditional search result pages — crawlability, backlinks, keyword signals.
• GEO measures whether an AI answer engine can read, parse, understand, and cite your content when generating a response.
• A site can rank well on Google and still be largely opaque to AI systems — missing structured data, no llms.txt, bot access blocked, thin factual density.

GEO Optimizer focuses on the technical and structural signals that AI answer engines use: robots.txt bot permissions, llms.txt presence and depth, JSON-LD schema richness, brand entity coherence, and content citability across 47 methods. These complement traditional SEO work rather than replacing it.

Try it online

Open-source vs GeoReady Platform

The CLI and web audit remain MIT-licensed and free. The GeoReady platform adds server-side continuity — monitoring, history, and team features — that a local CLI cannot provide on its own.

Quick Start

pip install geo-optimizer-skill

No install? One-shot audit with uv:

uvx --from geo-optimizer-skill geo audit --url https://yoursite.com

# Audit any site — get a score 0-100 with actionable recommendations
geo audit --url https://yoursite.com

# Audit a full sitemap and surface weakest pages first
geo audit --sitemap https://yoursite.com/sitemap.xml --max-urls 25

# Compare before/after versions of a page
geo diff --before https://yoursite.com/page-old --after https://yoursite.com/page-new

# Save history and detect regressions over time
geo audit --url https://yoursite.com --save-history --regression

# Show the saved trend for a site
geo history --url https://yoursite.com

# Passive AI visibility snapshot for a domain
geo monitor --domain yoursite.com

# Ask real AI engines: is my brand mentioned? Is my domain cited as a source?
# BYO API key — PERPLEXITY_API_KEY recommended (real web citations)
geo citations --brand "YourBrand" --domain yoursite.com --topic "your product category"

# Save or query archived AI answer snapshots
geo snapshots --query "best GEO tool" --from 2026-03-01 --to 2026-03-30

# Score citation quality inside an archived answer snapshot
geo snapshots --quality --snapshot-id 12 --target-domain yoursite.com

# Run recurring monitoring and generate an HTML trend report
geo track --url https://yoursite.com --report --output ./geo-track-report.html

# Auto-generate all missing files (robots.txt, llms.txt, schema, meta)
geo fix --url https://yoursite.com --apply

# Generate llms.txt from sitemap
geo llms --base-url https://yoursite.com --output ./public/llms.txt

# Generate JSON-LD schema
geo schema --type faq --url https://yoursite.com

What it checks

Score bands: 86-100 Excellent · 68-85 Good · 36-67 Foundation · 0-35 Critical

Bonus checks (informational, do not affect score):

Plus a separate Citability Score (0-100) measuring content quality across 47 methods: Quotation +41% · Statistics +33% · Fluency +29% · Cite Sources +27% · and 43 more.

Additional tools

geo coherence --sitemap https://example.com/sitemap.xml  # Cross-page terminology consistency
geo logs --file access.log                                # AI Crawler Activity — crawler evidence from user-agent logs
geo access --url https://example.com                      # Agent Access Audit — browser vs AI bot access simulation
geo citations --brand "Acme" --domain acme.com            # AI Citation Check — are you cited by answer engines? (BYO key)
geo authority --sitemap https://example.com/sitemap.xml   # Topic Authority — multi-page entity coverage, clusters, pillars

GEO Optimizer checks whether websites can be crawled, understood, cited, and monitored by AI answer engines:

• Crawled — robots.txt, CDN access, AI-bot reachability
• Understood — schema, llms.txt, content structure
• Cited — citability signals across 47 research-backed methods
• Monitored — geo logs (crawler evidence) and geo access (access simulation)

Note on wording: AI Crawler Activity reports crawler evidence from server-log user-agents. Agent Access Audit reports citation readiness (whether bots can reach and parse the page). For actual answer-engine checking — "does the AI mention my brand and cite my domain?" — use geo citations with your own API key (Perplexity Sonar returns the real source URLs; OpenAI/Anthropic/Groq reveal parametric brand knowledge).

Optional LLM-powered analysis (pip install geo-optimizer-skill[llm]): brand sentiment, citation attribution, multi-turn persistence, cross-platform citation map, prompt library.

Output formats

geo audit --url https://example.com --format text     # Human-readable (default)
geo audit --url https://example.com --format json      # Machine-readable
geo audit --sitemap https://example.com/sitemap.xml    # Batch sitemap audit (text)
geo audit --sitemap https://example.com/sitemap.xml --format json  # Batch sitemap audit (JSON)
geo audit --url https://example.com --format rich      # Colored terminal
geo audit --url https://example.com --format html      # Self-contained report
geo audit --url https://example.com --format sarif     # GitHub Code Scanning
geo audit --url https://example.com --format junit     # Jenkins, GitLab CI
geo audit --url https://example.com --format github    # GitHub Actions annotations
geo monitor --domain example.com                       # Passive AI visibility readiness
geo snapshots --query "best GEO tool"                 # Saved AI answer archive
geo snapshots --quality --snapshot-id 12              # Citation quality tiers for a saved answer
geo history --url https://example.com                  # Saved score trend
geo track --url https://example.com --report           # Monitoring HTML report

The JSON output format is intended to remain stable across minor versions and acts as the machine-readable integration contract for the GeoReady platform.

CI/CD Integration

# .github/workflows/geo.yml
- uses: Auriti-Labs/[email protected]
  with:
    url: https://yoursite.com
    min-score: 70        # Fail if score drops below 70
    format: sarif        # Upload to GitHub Security tab

Works with GitHub Actions, GitLab CI, Jenkins, CircleCI, and any CI that runs Python.

For longitudinal checks, persist snapshots and fail on regressions:

geo audit --url https://yoursite.com --save-history --regression

MCP Server

Use GEO Optimizer from Claude, Cursor, Windsurf, or any MCP client:

pip install geo-optimizer-skill[mcp]
claude mcp add geo-optimizer -- geo-mcp

Then ask: "audit my site and fix what's missing"

Use as AI Context

Load the right file into your AI assistant for GEO expertise:

Internal Skill System

The repository now includes a structured internal skill catalog for maintainers at src/geo_optimizer/skills/catalog/ plus validation rules and examples. See docs/skill-system.md for the v1 architecture.

Python API

from geo_optimizer import audit

result = audit("https://example.com")
print(result.score)                      # 85
print(result.band)                       # "good"
print(result.citability.total_score)     # 72
print(result.score_breakdown)            # {"robots": 18, "llms": 14, ...}
print(result.recommendations)            # ["Add FAQPage schema..."]

Async variant:

from geo_optimizer import audit_async
result = await audit_async("https://example.com")

Show your GEO score

Add a live GEO score badge to your README — like a coverage badge, but for AI visibility:

[![GEO Score](https://geoready.dev/badge?url=https://yoursite.com)](https://geoready.dev?utm_source=badge)

HTML variant for docs sites:

<a href="https://geoready.dev?utm_source=badge"><img src="https://geoready.dev/badge?url=https://yoursite.com" alt="GEO Score"></a>

Colors: 86-100 green · 68-85 cyan · 36-67 yellow · 0-35 red. Re-audited and cached hourly — improve your site, watch the badge change. No account needed.

Plugin System

Extend the audit with custom checks via entry points:

[project.entry-points."geo_optimizer.checks"]
my_check = "mypackage:MyCheck"

See examples/example_plugin.py for a working example.

Research Foundation

We focus on technical infrastructure (robots.txt, llms.txt, schema, meta) over content rewriting. The research confirms: if crawlers can't find and parse your content, prose optimization doesn't matter.

GEO Optimizer translates these findings into technical and content-level signals that can be operationally audited and tracked over time.

Roadmap

This project follows a deliberate release cadence — focused waves, not noisy patches.

Next focus areas: signal architecture, retrieval surface analysis, scoring recalibration, and structural pattern recognition. The v5.0 cycle represents a broader architectural evolution.

Full release calendar, philosophy, and direction → docs/ROADMAP.md

Security

All URL inputs are validated against private IP ranges (RFC 1918, loopback, link-local, cloud metadata) with DNS pinning before any request. See SECURITY.md for reporting vulnerabilities.

Contributing

git clone https://github.com/YOUR_USERNAME/geo-optimizer-skill.git
cd geo-optimizer-skill && pip install -e ".[dev]"
pytest tests/ -v   # 1682 tests, all mocked

Bug reports · Feature requests · CONTRIBUTING.md

Star History