Aeo Competitor Monitor

AEO Competitor Monitor

> Source: github.com/psyduckler/aeo-skills > Part of: AEO Skills Suite

Track which competitors get cited in AI Overviews — and how that changes over time.

Why This Matters

AI Overviews create a new competitive landscape. Influence happens at retrieval, not inside the model — the sources Gemini cites for your key prompts form the recurring retrieval set, and those are your real competitors. Gemini is search-first, searching before nearly every answer — influence compounds through repeated inclusion in this set. Tracking citation share over time reveals shifts in the recurring retrieval set:

• Who's gaining ground — new content entering the recurring retrieval set
• Who's losing ground — previously-cited pages dropping out of the candidate set
• Market dynamics — how the retrieval set shifts with content updates, algorithm changes
• Your relative position — where you stand in the candidate set vs competitors

Requirements

• Gemini API key (free) — set as GEMINI_API_KEY env var
• Python 3.9+
• No pip dependencies (stdlib only)

Usage

Scan — Run a new competitive scan

# Scan two prompts, tracking three competitors
GEMINI_API_KEY="$GEMINI_API_KEY" python3 scripts/monitor.py scan \
    --prompts "best SEO tools" "content optimization software" \
    --competitors acme.com surferseo.com semrush.com \
    --data-file monitor-data.json

# With custom run count
GEMINI_API_KEY="$GEMINI_API_KEY" python3 scripts/monitor.py scan \
    --prompts "best SEO tools" \
    --competitors acme.com surferseo.com \
    --data-file monitor-data.json \
    --runs 30

Report — Generate a comparison report

# Text report
python3 scripts/monitor.py report --data-file monitor-data.json

# JSON report
python3 scripts/monitor.py report --data-file monitor-data.json --output json

Alerts — Check for threshold violations

# Check alerts against thresholds
python3 scripts/monitor.py alerts --data-file monitor-data.json --config alerts.json

# JSON output
python3 scripts/monitor.py alerts --data-file monitor-data.json --config alerts.json --output json

Run from the skill directory. Resolve scripts/monitor.py relative to this SKILL.md.

Options

Scan Options

| Option | Default | Description | |--------|---------|-------------| | --prompts | (required) | One or more prompts to scan | | --competitors | (required) | One or more competitor domains to track | | --data-file | monitor-data.json | Path to the data file (created if missing) | | --runs | 20 | Runs per prompt | | --model | gemini-3-flash-preview | Gemini model | | --concurrency | 5 | Max parallel API calls |

Report Options

| Option | Default | Description | |--------|---------|-------------| | --data-file | monitor-data.json | Path to the data file | | --output | text | Output format: text or json |

Alerts Options

| Option | Default | Description | |--------|---------|-------------| | --data-file | monitor-data.json | Path to the data file | | --config | alerts.json | Alert config file path | | --output | text | Output format: text or json |

Alert Configuration

Create an alerts.json file with threshold rules. Alerts monitor shifts in the recurring retrieval set:

{
  "alerts": [
    {"type": "competitor_above", "domain": "competitor.com", "threshold": 50, "prompt": "*"},
    {"type": "self_below", "domain": "mybrand.com", "threshold": 30, "prompt": "*"},
    {"type": "position_drop", "domain": "mybrand.com", "positions": 3, "prompt": "*"},
    {"type": "new_competitor", "prompt": "*", "min_citation_rate": 20}
  ]
}

Alert Types

| Type | Fires when | What it means | |------|-----------|---------------| | competitor_above | A competitor's citation rate exceeds threshold % | Competitor has entered or solidified their position in the recurring retrieval set | | self_below | Your own citation rate drops below threshold % | You're falling out of the candidate set — content refresh needed | | position_drop | Your citation position drops by N positions | Your structural influence is declining even if still cited | | new_competitor | A domain not seen in previous scans appears with >N% citation rate | New entrant into the recurring retrieval set — potential threat |

Set prompt to "*" to check all tracked prompts, or specify a single prompt string.

Alert Output Example

⚠️  3 alert(s) triggered:
============================================================
  🔴 COMPETITOR ABOVE THRESHOLD
     semrush.com citation rate (85%) exceeds threshold (50%) for "best SEO tools"

  🟡 SELF BELOW THRESHOLD
     mybrand.com citation rate (15%) below threshold (30%) for "content optimization"

  🆕 NEW COMPETITOR
     New competitor newsite.io appeared with 35% citation rate for "best SEO tools"

Output

Scan Output

After each scan, prints a quick summary:

Scan complete: 2 prompts × 20 runs
Saved to monitor-data.json (scan #3)

Quick Results:
  "best SEO tools":
    acme.com  — 75% citation rate
    surferseo.com  — 60% citation rate
    semrush.com    — 85% citation rate

  "content optimization software":
    acme.com  — 80% citation rate
    surferseo.com  — 45% citation rate
    semrush.com    — 55% citation rate

Report Output

Competitor Monitor Report
Data: monitor-data.json (3 scans, 14 days)
================================================================

CITATION SHARE BY PROMPT:

"best SEO tools" (3 scans):
  Competitor        Latest    Avg     Trend
  ─────────────────────────────────────────
  semrush.com        85%      80%     ↑ +10%
  acme.com      75%      70%     → stable
  surferseo.com      60%      65%     ↓ -5%

"content optimization software" (3 scans):
  Competitor        Latest    Avg     Trend
  ─────────────────────────────────────────
  acme.com      80%      75%     ↑ +10%
  semrush.com        55%      60%     ↓ -10%
  surferseo.com      45%      50%     ↓ -5%

OVERALL CITATION SHARE (across all prompts):
  semrush.com    — 70% avg citation rate
  acme.com  — 78% avg citation rate
  surferseo.com  — 53% avg citation rate

NOTABLE CHANGES:
  ↑ acme.com gained +10% on "content optimization software"
  ↓ semrush.com dropped -10% on "content optimization software"

CITED URLS:
  acme.com:
    - https://acme.com/blog/content-optimization (12x)
    - https://acme.com/product (5x)
  ...

Data File Format

The data file is append-only JSON. Each scan adds an entry:

{
  "scans": [
    {
      "timestamp": "2025-03-15T14:30:00Z",
      "model": "gemini-3-flash-preview",
      "runs_per_prompt": 20,
      "results": {
        "best SEO tools": {
          "successful_runs": 20,
          "competitors": {
            "acme.com": {
              "citation_rate": 75,
              "citation_count": 15,
              "cited_urls": {"https://acme.com/blog/seo-tools": 10},
              "mentioned": true,
              "excerpts": ["Acme is a leading content optimization..."]
            }
          },
          "other_sources": [
            {"domain": "g2.com", "citation_rate": 40}
          ]
        }
      }
    }
  ]
}

Tips

• Run scans weekly or biweekly for meaningful trend data
• Track 5-10 prompts and 3-5 competitors for focused insights
• After publishing new content, wait 2-4 weeks before expecting citation changes
• Use alongside aeo-analytics-free for your own brand tracking
• Use aeo-ai-overview-simulator for deep-dive into specific prompts
• Citation rates fluctuate naturally (±5-10%) — look for sustained trends over 3+ scans

Further Reading

Notes

• Gemini API key in macOS Keychain under google-api-key
• Data file is created automatically on first scan
• Never overwrites historical data — each scan appends
• Retries with exponential backoff for API failures
• API cost: ~400 calls per scan (20 prompts × 20 runs). Free tier supports this.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: psyduckler
• Source: psyduckler/aeo-skills
• License: MIT

Install and usage instructions live in the source repository linked above.