🌍 E-GEO

Generative Engine Optimization (GEO) & Answer Engine Optimization (AEO) for AI-Powered Search

🚀 One command. Premium results. Rank higher in ChatGPT, Perplexity, Claude, and Gemini.

📖 Docs • 🐛 Issues • 💬 Discussions • 📝 Research Paper

✨ What is E-GEO?

E-GEO is an open-source Generative Engine Optimization (GEO) and Answer Engine Optimization (AEO) toolkit that transforms your website content to rank higher in AI-powered search engines — including ChatGPT, Perplexity, Google AI Overviews, Claude, and Gemini.

Also known as AI SEO or LLM SEO, GEO is the practice of optimizing content so that generative AI engines can crawl, understand, cite, and recommend it. E-GEO automates this entire process.

Based on the E-GEO research paper (arXiv:2511.20867), it applies the 10 universal features that consistently improve AI-engine rankings — competitive framing, citation optimization, structured data, and semantic density improvements backed by peer-reviewed findings.

✅ No learning curve — One command to optimize
✅ Research-backed — Based on peer-reviewed findings
✅ Production-ready — Copy-paste optimized content
✅ Multi-engine — Optimizes for ChatGPT, Perplexity, Gemini, Claude & Google AI Overviews
✅ Full pipeline — Analyze → Rank → Rewrite → Schema in one command

/geo https://yoursite.com/pricing

↓

geo-output/
├── report.md
├── optimized/
│   └── pricing.md
└── schema/
    └── pricing.json

📈 Why AI Visibility Matters in 2026

AI search engines give one synthesized answer and cite a handful of sources. If your site isn't one of them, you're invisible — even if you rank #1 on Google.

User asks ChatGPT: "What's the best GEO tool?"

ChatGPT: "According to [Competitor], the best tool is..."
          ↑ They get cited. You don't.

ChatGPT 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 study on GPT-4).
844,000+ sites already ship an llms.txt. Is yours one of them?

Traditional SEO optimizes for blue links. GEO optimizes for citations in AI-generated answers. E-GEO is the open-source tool that bridges this gap.

🚀 Quick Start (3 Steps)

1. Install

Copy the .claude/ folder to your project:

cp -r /path/to/eGEOagents/.claude .

2. Activate

In Claude Code, switch to GEO mode:

/output-style geo-optimizer

3. Optimize

Run your first optimization:

/geo https://yoursite.com

🧩 Install as Skills (skills.sh)

Install the complete skill collection:

npx skills add https://github.com/mverab/eGEOagents

Install one skill only:

npx skills add https://github.com/mverab/eGEOagents --skill competitive-analysis

Validate parser discovery before shipping updates:

npx skills add https://github.com/mverab/eGEOagents --list

Verify indexing pages:

Collection: skills.sh/mverab/egeoagents
Owner: skills.sh/mverab

📋 Commands

Command	What it does
`/geo <url>`	Full pipeline - Analyze, rank, rewrite, schema
`/geo:audit <url>`	Analysis only, no changes
`/geo:optimize <file>`	Optimize local content file
`/geo:batch <folder>`	Process entire folder
`/geo:report`	Generate executive report
`/geo:compete <query>`	Competitive analysis
`/geo:loop <domain>`	One bounded loop-mode iteration over a workspace domain

📊 What You Get

After running /geo:

geo-output/
├── report.md           # Executive summary + scores
├── analysis.json       # Raw analysis data
├── optimized/
│   └── pricing.md      # Rewritten content (ready to use)
├── schema/
│   └── pricing.json    # JSON-LD markup (copy to site)
└── checklist.md        # Step-by-step implementation

🎯 Results: Backed by Research

E-GEO is grounded in peer-reviewed research from the E-GEO research paper (arXiv:2511.20867), building on foundational work by Aggarwal et al. (Princeton, KDD 2024) — the original study that defined Generative Engine Optimization as a discipline.

The E-GEO paper reports that:

Competitive framing produces the strongest immediate ranking lift among all GEO strategies tested.
A universal optimization strategy (applying all 10 features together) outperforms individual heuristics by a wide margin.
The 10 GEO features (ranking emphasis, user intent matching, competitive edge, social proof, authority signals, scannability, citation density, structured data, factual language, and freshness) consistently appear in higher-ranking content across ChatGPT, Perplexity, and Gemini.

Feature	What E-GEO Does
Ranking Emphasis	Positions your content as the top choice
User Intent	Directly answers what users are looking for
Competitive Edge	Highlights your unique advantages
Social Proof	Integrates trust signals and testimonials
Authority	Establishes expert, confident tone
Scannability	Structures for easy AI parsing

Results vary by content quality and competition. See the paper for full methodology and findings: arXiv:2511.20867.

🧪 Reproducible Results

E-GEO ships an evaluation harness so you can measure prompt quality yourself — no trust required. It scores whether the GEO rewriter moves a target item up in an LLM-simulated ranking.

pip install pyyaml jsonschema

# Deterministic, offline smoke run (no API key needed)
GEO_EVAL_MOCK=1 python geo_eval.py evaluate \
  --dataset eval/datasets/geo_smoke.jsonl --limit 5 --verbose

This is the exact check that runs in CI on every pull request. Reported metrics: avg_rank_improvement, win_rate, and stderr_rank_improvement.

Honest scope: these numbers are a proxy produced by an LLM-ranker, not a measurement of real ChatGPT/Perplexity rankings. See docs/evaluation.md for the full methodology, metric definitions, and limitations.

🖥️ Standalone CLI (`egeo`)

Beyond Claude Code, E-GEO ships a runtime-agnostic command line so the same GEO engine runs anywhere Python runs — local shells, notebooks, Docker, or CI. The CLI is a thin wrapper around the exact same geo_eval.py and llm_client.py modules used by the Claude Code agents, so there is no duplicated optimization logic — both runtimes share one source of truth.

Install

# From the repo root — installs the `egeo` console script + deps
pip install -e .

# ...or run without installing (deps: pip install pyyaml jsonschema)
python -m egeo --help

Commands

Command	What it does
`egeo optimize <file>`	Full pipeline — analyze → rank → rewrite → schema, writes `report.md`, `optimized/.md`, `schema/.json`, `analysis.json`
`egeo evaluate`	Run the evaluation harness (reuses `geo_eval.py`, identical metrics)
`egeo optimize-prompts`	Meta-optimize the rewriter prompt (non-destructive by default)
`egeo runtimes`	List available runtime adapters and their status
`egeo loop <run\|collect\|doctor>`	Loop mode — plan a run, run a collector, or check the workspace

# Optimize a local content file (output dir defaults to ./geo-output)
egeo optimize examples/sample-input.md --out-dir ./geo-output

# Score prompt quality on a dataset
egeo evaluate --dataset eval/datasets/geo_smoke.jsonl --limit 5

# Inspect the runtime adapters
egeo runtimes

Offline / deterministic mode

Every command honors GEO_EVAL_MOCK=1, which swaps in a deterministic mock LLM client — no API key required. This is exactly how the CLI is exercised in CI:

GEO_EVAL_MOCK=1 egeo optimize examples/sample-input.md --out-dir /tmp/egeo
GEO_EVAL_MOCK=1 egeo evaluate --dataset eval/datasets/geo_smoke.jsonl --limit 3

Supported Runtimes

E-GEO exposes a small runtime adapter layer so the same agents (Analyzer, Ranker, Rewriter, Indexer) can be driven by different execution hosts:

Runtime	Aliases	Mode	Status	Description
`python`	`cli`, `local`	in-process	✅ Available	Pure-Python runtime behind the `egeo` CLI. Runs the full pipeline in-process and honors `GEO_EVAL_MOCK` for offline, deterministic runs.
`claude-code`	`claude`	host-executed	✅ Available	Executes the `.claude/` agents through Claude Code `/geo` slash commands on the host. Auto-detected when a `.claude/` directory is present.

Run egeo runtimes to print the live status of each adapter in your environment. Additional hosts (Cursor, Codex, Windsurf, …) can be added by implementing the RuntimeAdapter interface in egeo/runtimes.py.

🔁 Loop Mode (continuous GEO)

One-shot GEO answers "how is this page doing today?". Loop mode answers "what changed, and what should I do about it?" — week after week, without you asking. It is fully opt-in: /geo <url> and egeo optimize behave exactly as before and never need a workspace.

The workspace (`$EGEO_HOME`)

All loop state lives outside the repo, in the workspace resolved from $EGEO_HOME (default ~/.egeo/), so git pull never touches your data:

$EGEO_HOME/
├── LOG.md                        # append-only activity feed (one line per event)
├── config.yaml                   # cadence, models, budgets, scaling weights
├── SUBSTRATE.md                  # the contract, vendored on bootstrap
├── signals/<slug>.md             # evidence — deduped, frequency-counted
├── docs/<slug>.md                # durable knowledge — analyses, decisions
├── data/<collector>/*.jsonl      # raw collector output (not artifacts)
├── domains/<loop>/README.md      # charter: focus, backlog, run Timeline
└── prompts/                      # optimized prompts (repo prompts/ stay pristine)

The layout and the artifact rules are defined by SUBSTRATE.md and mechanically enforced by python -m egeo.substrate_lint.

Commands

Command	What it does
`egeo loop doctor`	Bootstrap the workspace if missing, then health-check it (layout, config, budgets, substrate lint)
`egeo loop collect serp`	Record a search-result snapshot (Brave API) into `data/serp/*.jsonl`
`egeo loop collect page`	Record a page snapshot (hash, title, meta, JSON-LD types, word count) into `data/page/*.jsonl`
`egeo loop run <domain>`	Resolve and print the run plan — current focus, fresh collector deltas, candidate signals
`/geo:loop <domain>`	Execute one bounded loop iteration in Claude Code (the agent does the interpretive work)

# 1. Create the workspace
egeo loop doctor

# 2. Describe what you want watched: $EGEO_HOME/domains/example-com/README.md
#    (## Charter, ## Cadence, ## Current focus, ## Backlog, ## Timeline)

# 3. Collect ground truth
export BRAVE_API_KEY=...
egeo loop collect serp --query "best geo tool" --target-domain example.com
egeo loop collect page --url https://example.com/pricing

# 4. See what a run would do — writes nothing
egeo loop run example-com --dry-run

# 5. Do the run (Claude Code, or headless)
claude -p "/geo:loop example-com"

egeo loop run is LLM-free by design: it is the trigger seam that prepares and validates the plan. The reasoning happens in .claude/skills/geo-loop/SKILL.md, which enforces the run contract: one unit of work, one Timeline entry ending in Outcome: success|partial|failure|no-op, one LOG.md line, verified before exit.

Collectors

Collectors are the loop's senses: deterministic, LLM-free, budget-aware, and append-only. Every collector honours the same 10-point contract (collectors/README.md) — in short: write JSONL to $EGEO_HOME/data/<name>/, one record per observation with a schema_version, respect the daily budget in config.yaml, append exactly one LOG.md line per pass, and fail loudly instead of writing a partial or fabricated record.

Collector	Needs	Output
`serp`	`BRAVE_API_KEY`	Top-10 results per query + your target's position
`page`	nothing	`content_hash`, title, meta description, JSON-LD types, word count

Both accept --fixture for offline, deterministic runs — that is how they are tested without touching the network.

Scheduling (Hermes cron reference)

Any scheduler drives the same commands. Pin provider and model per job, and for anything more frequent than weekly deliver locally and let a weekly digest do the notifying:

# hourly — local delivery only (JSONL + LOG line, no notification)
0 * * * *   provider=anthropic model=claude-sonnet-4-5 deliver=local \
            egeo loop collect page --url https://example.com/pricing

# daily — one bounded loop run
30 6 * * *  provider=anthropic model=claude-sonnet-4-5 deliver=local \
            claude -p "/geo:loop example-com"

# weekly — the only job that pings you
0 9 * * 1   provider=anthropic model=claude-opus-4-1 deliver=notify \
            claude -p "Summarize $EGEO_HOME/LOG.md for the past 7 days"

🆚 E-GEO vs Other GEO Tools

Feature	E-GEO	GEO Optimizer	GEO-optim/GEO	Awesome GEO	Traditional SEO
Type	CLI + Claude Code	CLI + MCP	Research repo	Curated list	—
Content Rewriting	✅ Full pipeline	⚠️ Audit only	❌	❌	❌ No
AI-Ranking Simulation	✅ LLM-based	❌	❌	❌	❌ No
Schema Generation	✅ Auto JSON-LD	⚠️ Partial	❌	❌	❌ Manual
Competitive Analysis	✅ Built-in	❌	❌	❌	❌ No
Academic Foundation	✅ arXiv:2511.20867	✅ KDD 2024	✅ Original GEO paper	❌	❌ Heuristics
Multi-Runtime	✅ Python + Claude Code	✅ Python + MCP	❌	❌	❌
llms.txt Support	✅	✅	❌	📖 Listed	❌
Cost	Free / MIT	Free / MIT	Free	Free	Expensive

E-GEO is the only open-source GEO tool that combines content rewriting, ranking simulation, and schema generation in a single pipeline. Others focus on auditing or listing — E-GEO does the full optimization.

💎 Premium Output

E-GEO delivers outputs that look like they came from a $100M company:

┌─────────────────────────────────────────────────────────────┐
│  🎯 GEO AUDIT REPORT                                        │
├─────────────────────────────────────────────────────────────┤
│  URL: yoursite.com/pricing                                  │
│  Score: 78/100                                              │
│  Ranking Potential: ████████░░ 78%                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ✅ STRENGTHS                                               │
│  • Clear value proposition                                  │
│  • Good content structure                                   │
│                                                             │
│  ⚠️ GAPS                                                    │
│  • Missing social proof → Add customer count                │
│  • No urgency signals → Add limited-time offer              │
│                                                             │
│  📈 PRIORITY ACTIONS                                        │
│  1. Add testimonials (+15 points)                           │
│  2. Include pricing comparison (+10 points)                 │
│  3. Add schema markup (+5 points)                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

🤖 How It Works

E-GEO uses 4 specialized AI agents orchestrated by Claude Code:

Agent	What it does	Output
🔍 Analyzer	Extracts content, scores GEO signals, identifies gaps	`analysis.json`
📊 Ranker	Simulates AI-engine ranking, predicts positions	Baseline score
✍️ Rewriter	Optimizes content while preserving brand voice	`optimized/*.md`
🗂️ Indexer	Generates schema markup and technical assets	`schema/*.json`

📁 What's Included

.claude/
├── CLAUDE.md                    # System knowledge base
├── output-styles/
│   └── geo-optimizer.md         # Premium formatting mode
├── agents/
│   ├── geo-analyzer.md          # Content analysis
│   ├── geo-rewriter.md          # Content optimization
│   ├── geo-ranker.md            # Ranking simulation
│   └── geo-indexer.md           # Schema generation
├── skills/
│   ├── competitive-analysis/    # Auto-triggered competitor analysis
│   ├── content-scoring/         # Auto-triggered scoring
│   ├── schema-generator/        # Auto-triggered schema
│   └── geo-loop/                # Loop-mode run contract
└── commands/
    ├── geo.md                   # Main command
    ├── geo-audit.md
    ├── geo-optimize.md
    ├── geo-batch.md
    ├── geo-report.md
    ├── geo-compete.md
    └── geo-loop.md

egeo/                            # Standalone CLI package
├── cli.py                       # `egeo` entrypoint
├── loop.py                      # `egeo loop run|collect|doctor`
├── workspace.py                 # $EGEO_HOME resolution + bootstrap
└── substrate_lint.py            # SUBSTRATE.md enforcement

collectors/                      # Deterministic, LLM-free senses
├── README.md                    # The collector contract
├── serp.py                      # Brave search snapshots
├── page.py                      # Page snapshots
└── fixtures/                    # Offline test data

SUBSTRATE.md                     # Workspace/artifact contract

🎁 Perfect For

📚 Documentation

Resource	Description
📖 Getting Started	Step-by-step tutorial
⚙️ How It Works	Technical deep dive
❓ FAQ	Common questions answered
🧩 skills.sh Playbook	Listing, ranking, and metadata checklist
🧪 Evaluation Harness	Dataset format, commands, metrics, and honest limitations
📝 Usage Guide	Complete command reference
📝 Research Paper	The science behind E-GEO

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick ways to contribute:

Report bugs via issues
Submit pull requests for features
Improve documentation
Share your GEO results

🔍 SEO & AI Search Glossary

E-GEO covers the full spectrum of AI search optimization. If you're searching for any of these, you're in the right place:

Term	What it means
GEO (Generative Engine Optimization)	Optimizing content for AI answer engines like ChatGPT, Perplexity, Gemini
AEO (Answer Engine Optimization)	Structuring content so AI engines can parse and cite it
AI SEO	Adapting traditional SEO for AI-powered search
LLM SEO	Optimization specifically for large language model responses
AI Visibility	How often and how well your brand appears in AI-generated answers
Citation Tracking	Monitoring whether AI engines cite your site as a source
llms.txt	A standard file (like robots.txt) that tells AI crawlers what content to prioritize

📜 License

MIT License - use it, modify it, sell with it. See LICENSE for details.

🙋 Support & Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Research: E-GEO Paper (arXiv:2511.20867)

🚀 Ready to Rank Higher?

# Install
cp -r eGEOagents/.claude .

# Activate (in Claude Code)
/output-style geo-optimizer

# Optimize your first page
/geo https://yoursite.com

Built for the AI-first web — optimize your content for ChatGPT, Perplexity, Claude, and Gemini with E-GEO, the open-source GEO tool. 🌐

Made with ❤️ by Vera Badias • Based on research from arXiv:2511.20867

🤖 This project is AI-assisted. See AI Transparency for details.

eGEOagents

At a glance

README

🌍 E-GEO

Generative Engine Optimization (GEO) & Answer Engine Optimization (AEO) for AI-Powered Search

✨ What is E-GEO?

📈 Why AI Visibility Matters in 2026

🚀 Quick Start (3 Steps)

1. Install

2. Activate

3. Optimize

🧩 Install as Skills (skills.sh)

📋 Commands

📊 What You Get

🎯 Results: Backed by Research

🧪 Reproducible Results

🖥️ Standalone CLI (`egeo`)

Install

Commands

Offline / deterministic mode

Supported Runtimes

🔁 Loop Mode (continuous GEO)

The workspace (`$EGEO_HOME`)

Commands

Collectors

Scheduling (Hermes cron reference)

🆚 E-GEO vs Other GEO Tools

💎 Premium Output

🤖 How It Works

📁 What's Included

🎁 Perfect For

📚 Documentation

🤝 Contributing

🔍 SEO & AI Search Glossary

📜 License

🙋 Support & Community

🚀 Ready to Rank Higher?

Comments (0)

eGEOagents

At a glance

README

🌍 E-GEO

Generative Engine Optimization (GEO) & Answer Engine Optimization (AEO) for AI-Powered Search

✨ What is E-GEO?

📈 Why AI Visibility Matters in 2026

🚀 Quick Start (3 Steps)

1. Install

2. Activate

3. Optimize

🧩 Install as Skills (skills.sh)

📋 Commands

📊 What You Get

🎯 Results: Backed by Research

🧪 Reproducible Results

🖥️ Standalone CLI (egeo)

Install

Commands

Offline / deterministic mode

Supported Runtimes

🔁 Loop Mode (continuous GEO)

The workspace ($EGEO_HOME)

Commands

Collectors

Scheduling (Hermes cron reference)

🆚 E-GEO vs Other GEO Tools

💎 Premium Output

🤖 How It Works

📁 What's Included

🎁 Perfect For

📚 Documentation

🤝 Contributing

🔍 SEO & AI Search Glossary

📜 License

🙋 Support & Community

🚀 Ready to Rank Higher?

Comments (0)

🖥️ Standalone CLI (`egeo`)

The workspace (`$EGEO_HOME`)