onvoyage-ai/voyage-geo-agent

Quick Start · Claude Code · CLI Reference · Models · Docs

---

Sample Report

Open source Generative Engine Optimization (GEO) CLI tool. Analyze how AI models (ChatGPT, Claude, Gemini, Perplexity, DeepSeek, Grok, Llama) reference and recommend your brand.

SEO analytics, but for AI search engines.

How It Works

Brand Input → Research → Generate Queries → Run Against AI Models → Analyze → Report

1. Research your brand — scrapes your website, builds a brand profile with competitors, USPs, keywords
2. Generate queries — creates realistic search queries real people would type into ChatGPT/Perplexity (brand-blind, so queries never mention your brand)
3. Execute — sends queries to multiple AI models via OpenRouter (or direct API keys)
4. Analyze — measures mention rate, sentiment, mindshare, competitor positioning, narrative themes, USP coverage gaps
5. Report — generates interactive HTML reports with charts, plus JSON/CSV/Markdown exports

Quick Start

Prerequisites

• Python 3.11+
• An OpenRouter API key (one key for all AI models), or individual provider API keys

Install

pip install voyage-geo

Or install from source:

git clone https://github.com/onvoyage-ai/voyage-geo-agent.git
cd voyage-geo-agent
pip install -e .

Configure API Keys

cp .env.example .env
# Edit .env — at minimum, set OPENROUTER_API_KEY

Run an Analysis

# Full pipeline
python3 -m voyage_geo run -b "YourBrand" -w "https://yourbrand.com" --no-interactive

# Or with specific providers
python3 -m voyage_geo run -b "YourBrand" -w "https://yourbrand.com" \
  -p chatgpt,gemini,claude,perplexity-or -f html,json,csv,markdown --no-interactive

Using with AI Agents

Voyage GEO ships an interactive skill that works with Claude Code, OpenClaw, and any agent that supports the SKILL.md format.

Install Skills

For this package, use this skill entrypoint:

curl -s https://raw.githubusercontent.com/onvoyage-ai/voyage-geo-agent/main/voyage-geo-aeo-analysis/SKILL.md

If needed, fallback to GitHub-hosted instructions:

curl -s https://raw.githubusercontent.com/onvoyage-ai/voyage-geo-agent/main/AGENTS.md

Install Local Agent Command

Tell your agent to fetch and follow the install instructions:

https://raw.githubusercontent.com/onvoyage-ai/voyage-geo-agent/main/AGENTS.md

The agent will pip install voyage-geo and create the skill automatically. Works with Claude Code, OpenClaw, and any agent that supports SKILL.md.

Available Skills

App Mode (Optional GUI)

You can run an optional local GUI + API without changing CLI/agent workflows.

Install app extras:

pip install "voyage-geo[app]"

Start app mode:

python3 -m voyage_geo app --host 127.0.0.1 --port 8765

Then open http://127.0.0.1:8765.

• GUI handles run discovery, job progress, and logs.
• Backend API (/api/*) is the shared glue for GUI + Claude/Codex automation.
• Existing CLI and skill-based agent mode continue to work unchanged.

Control Center Preview

The local GUI includes:

• Start GEO runs and leaderboard runs from a visual form
• Model selection with click-to-toggle checkboxes
• Live jobs table + streaming logs
• Past runs browser with one-click report opening
• Auto-generated HTML report fallback when only JSON exists

CLI Reference

# Full analysis pipeline
python3 -m voyage_geo run -b "" -w "" -p chatgpt,gemini,claude --no-interactive

# Research a brand (builds profile)
python3 -m voyage_geo research "" -w ""

# List configured providers
python3 -m voyage_geo providers

# Health check providers
python3 -m voyage_geo providers --test

# Generate reports from an existing run
python3 -m voyage_geo report -r  -f html,json,csv,markdown

# Build trend index from completed snapshots
python3 -m voyage_geo trends-index -o ./data/runs --out-file ./data/trends/snapshots.json

# Query trend series for one brand (includes competitor-relative fields)
python3 -m voyage_geo trends -b "YourBrand" --metric overall_score --json

# Generate interactive HTML trends dashboard
python3 -m voyage_geo trends-dashboard -b "YourBrand"

# Start optional local GUI + API mode
python3 -m voyage_geo app --host 127.0.0.1 --port 8765

# List past runs
python3 -m voyage_geo runs

# Show version
python3 -m voyage_geo version

Key Flags for run

Supported AI Models

All models are accessible through a single OpenRouter API key:

You can also use direct API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) for individual providers.

Alternative: BlockRun (Pay-per-Request)

BlockRun is a unified AI gateway supporting 30+ models with USDC micropayments on Base chain — no API keys or account creation required.

Set BLOCKRUN_WALLET_KEY to your Base wallet private key and fund with USDC. Usage:

# Single model
python3 -m voyage_geo run -b "YourBrand" -w "https://yourbrand.com" -p blockrun-gpt5 --no-interactive

# Multiple models (same wallet key)
python3 -m voyage_geo run -b "YourBrand" -w "https://yourbrand.com" \
  -p blockrun-gpt5,blockrun-claude,blockrun-gemini,blockrun-grok --no-interactive

Environment Variables

# OpenRouter (recommended — one key for all models)
OPENROUTER_API_KEY=sk-or-v1-...

# Direct provider keys (optional)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AI...
PERPLEXITY_API_KEY=pplx-...

# BlockRun (pay-per-request with crypto)
BLOCKRUN_WALLET_KEY=0x...

# Optional
LOG_LEVEL=info
VOYAGE_GEO_OUTPUT_DIR=./data/runs
VOYAGE_GEO_CONCURRENCY=3

Output Structure

Each run creates a self-contained directory:

data/runs//
├── metadata.json           # Run metadata (schema_version, status, brand/category, providers, config hash)
├── brand-profile.json      # Brand research output
├── queries.json            # Generated search queries
├── results/
│   ├── results.json        # All raw AI responses (+ schema_version)
│   └── by-provider/        # Split by provider
├── analysis/
│   ├── analysis.json       # Full analysis (+ schema_version)
│   ├── summary.json        # Executive summary (+ schema_version)
│   ├── snapshot.json       # Stable time-series KPI snapshot for trend indexing
│   └── *.csv               # CSV exports
└── reports/
    ├── report.html         # Interactive HTML report
    ├── report.json
    ├── report.md
    └── charts/             # PNG chart images

Data Contract Notes

• schema_version is included in persisted core artifacts (metadata.json, results/results.json, analysis/analysis.json, analysis/summary.json).
• analysis/snapshot.json is the canonical compact record for over-time visualization and database indexing.
• config_hash in metadata.json lets you detect whether runs are directly comparable.

Architecture

src/voyage_geo/
├── cli.py                # CLI entry (Typer + Rich)
├── config/               # Pydantic schemas, defaults, config loader
├── core/                 # Engine, pipeline, context, errors
├── providers/            # AI model providers (OpenRouter, OpenAI, Anthropic, Google, Perplexity)
├── stages/
│   ├── research/         # Stage 1: Brand research + web scraping
│   ├── query_generation/ # Stage 2: Generate search queries (keyword, persona, intent strategies)
│   ├── execution/        # Stage 3: Run queries against providers
│   ├── analysis/         # Stage 4: Analyze results (6 analyzers)
│   └── reporting/        # Stage 5: Generate reports (HTML/JSON/CSV/Markdown)
├── storage/              # File-based persistence
├── types/                # Shared Pydantic type definitions
└── utils/                # Text helpers, Rich progress displays

Extending

See the docs/ directory for detailed guides on adding providers, analyzers, and query strategies.

Development

pip install -e ".[dev]"
python3 -m pytest tests/ -v
python3 -m ruff check src/ tests/
python3 -m mypy src/voyage_geo/ --ignore-missing-imports

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.