CLAUDE.md

Overview

AI search visibility and brand radar tool for tracking how a brand appears in AI-generated search answers. Monitors AI answer citations, tracks share of voice in AI search vs competitors, analyzes cited domains and pages, and tracks impressions/mentions history. Uses our-seo-agent CLI or pre-fetched data for comprehensive AI visibility monitoring.

Quick Start

pip install -r scripts/requirements.txt

# AI visibility tracking
python scripts/ai_visibility_tracker.py --target example.com --json

# AI citation analysis
python scripts/ai_citation_analyzer.py --target example.com --json

Scripts

Script	Purpose	Key Output
`ai_visibility_tracker.py`	Track brand visibility in AI search results	AI impressions, mentions, share of voice, trends
`ai_citation_analyzer.py`	Analyze AI answer citations and source pages	Cited domains, cited pages, AI response analysis
`base_client.py`	Shared utilities	RateLimiter, ConfigManager, BaseAsyncClient

AI Visibility Tracker

# Current visibility overview
python scripts/ai_visibility_tracker.py --target example.com --json

# With competitor comparison
python scripts/ai_visibility_tracker.py --target example.com --competitor comp1.com --competitor comp2.com --json

# Historical trend (impressions/mentions)
python scripts/ai_visibility_tracker.py --target example.com --history --json

# Share of voice analysis
python scripts/ai_visibility_tracker.py --target example.com --sov --json

Capabilities:

AI impressions overview (how often brand appears in AI answers)
AI mentions overview (brand mention frequency across AI engines)
Share of Voice in AI search vs competitors
Impressions history over time (trend tracking)
Mentions history over time
SOV history and trend analysis
Competitor AI visibility comparison

AI Citation Analyzer

# Analyze AI citations for brand
python scripts/ai_citation_analyzer.py --target example.com --json

# Cited domains analysis
python scripts/ai_citation_analyzer.py --target example.com --cited-domains --json

# Cited pages analysis
python scripts/ai_citation_analyzer.py --target example.com --cited-pages --json

# AI response content analysis
python scripts/ai_citation_analyzer.py --target example.com --responses --json

Capabilities:

AI response analysis (how the brand appears in AI-generated answers)
Cited domains analysis (which source domains AI engines reference)
Cited pages analysis (which specific URLs get cited)
Citation sentiment and context analysis
Citation frequency ranking
Competitor citation comparison
Recommendation generation for improving AI visibility

Data Sources

Source	Purpose
`our-seo-agent` CLI	Primary data source (future); use `--input` for pre-fetched JSON
WebSearch / WebFetch	Supplementary live data
Notion MCP	Save audit report to database

Output Format

{
  "target": "example.com",
  "impressions": {
    "total": 15000,
    "trend": "increasing",
    "change_pct": 12.5
  },
  "mentions": {
    "total": 850,
    "trend": "stable",
    "change_pct": 2.1
  },
  "share_of_voice": {
    "brand_sov": 18.5,
    "competitors": [
      {"domain": "comp1.com", "sov": 25.3},
      {"domain": "comp2.com", "sov": 15.8}
    ]
  },
  "cited_domains": [...],
  "cited_pages": [...],
  "ai_responses_sample": [...],
  "recommendations": [...],
  "timestamp": "2025-01-01T00:00:00"
}

Notion Output (Required)

IMPORTANT: All audit reports MUST be saved to the OurDigital SEO Audit Log database.

Database Configuration

Field	Value
Database ID	`2c8581e5-8a1e-8035-880b-e38cefc2f3ef`
URL	https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef

Required Properties

Property	Type	Description
Issue	Title	Report title (Korean + date)
Site	URL	Tracked website URL
Category	Select	AI Search Visibility
Priority	Select	Based on SOV trend
Found Date	Date	Report date (YYYY-MM-DD)
Audit ID	Rich Text	Format: AI-YYYYMMDD-NNN

Language Guidelines

Report content in Korean (한국어)
Keep technical English terms as-is (e.g., AI Search, Share of Voice, Brand Radar)
URLs and code remain unchanged

4.3 KiB Raw Permalink Blame History