Monitor your brand's AI visibility across ChatGPT, Claude, Perplexity, and Gemini.
Version: 0.3.4
BotSee is an agent-first API that delivers structured data from every major AI search engine β competitors, keywords, sources, and raw responses β programmatically, from Claude Code and other AI coding platforms.
- Find competitors as AI search engines see them
- Measure share of voice vs competitors
- Identify which sources AI cites for your category
- Uncover exact search queries AI runs for your space
- Generate AI-optimized content from analysis data
- Track visibility over time with historical analysis
/install-plugin https://github.com/RivalSee/botsee
git clone https://github.com/RivalSee/botsee-skill.git
python3 botsee-skill/skills/botsee/botsee.py status- Python 3 (pre-installed on macOS)
- Claude Code, Codex, or any AI coding agent
# Step 1: Get signup URL (credit card flow)
/botsee signup
# Step 2: Visit the URL in browser, complete signup
# Step 3: Paste your API key in the chat
# Claude will automatically save it
# Step 4: Create site and generate content
/botsee create-site https://example.com
# Optional: Customize generation counts
/botsee create-site https://example.com --types 3 --personas 2 --questions 10
# Run analysis (~660 credits)
/botsee analyze
# Generate blog post (~15 credits, estimated)
/botsee content
# Check status and balance
/botsee# Step 1: Create signup token for USDC flow
/botsee signup --crypto
# Step 2: Initiate USDC payment on Base
/botsee signup-pay-usdc --amount-cents 250 --from-address 0xYOUR_WALLET
# Step 3: Check completion and save API key when ready
/botsee signup-status
# Step 4: Create site and generate content
/botsee create-site https://example.com
# Optional: Customize generation counts
/botsee create-site https://example.com --types 3 --personas 2 --questions 10
# Run analysis (~660 credits)
/botsee analyze
# Generate blog post (~15 credits, estimated)
/botsee content
# Check status and balance
/botsee
# Optional: Top up credits later with USDC
/botsee topup-usdc --amount-cents 5000 --from-address 0xYOUR_WALLETUse these natural language prompts to guide Claude through the complete BotSee workflow:
Install the BotSee plugin: /install-plugin https://github.com/RivalSee/botsee. Then sign me up for BotSee using my email user@example.com so I can analyze how AI search engines see my product.
Create a BotSee site for https://myproduct.com with 1 customer type, 2 personas, and 5 questions per persona. Set it up so I can run a competitive analysis.
Run a competitive analysis and show me the full list of competitors mentioned by AI search engines, including their mention percentages and what contexts they appear in.
Show me all the keywords that AI search engines associate with my product category, sorted by frequency.
Based on those keywords and competitor insights, give me 5 compelling blog post titles that would help us compete better in AI search results.
Write a full blog post for the first title, including our competitive position, opportunities, threats, and recommended actions based on the analysis data.
Total cost: ~725 credits ($7.25 at $0.01/credit) | Time: ~15 minutes Output: Competitor rankings with percentages, keyword frequency analysis, and strategic blog content
Shows current status, balance, and available commands.
π€ BotSee
βββββββββββββββ
π° Credits: 1,250
π Sites: 1
π Key: bts_live_abc123...
Signup for BotSee and get your API key. Default behavior is Signup with Credit Card (Stripe web flow).
New user (no API key):
# Step 1: Get signup URL
/botsee signup
# Step 2: Visit the URL, complete signup, and paste your API key in the chat
# Claude will automatically save it for you
# Step 3: Create your site
/botsee create-site https://example.comThe signup flow:
- Run
/botsee signupto get your unique signup URL - Visit the URL in your browser and complete signup
- Paste your API key in the chat (e.g., "My API key is bts_live_abc123")
- Claude automatically saves it - you can then run
/botsee create-site
Optional contact info:
/botsee signup --email you@example.com --name "Your Name" --company "Your Company"Contact fields are optional - the API will use defaults if not provided.
Existing user (has API key):
/botsee signup --api-key bts_live_YOUR_KEYValidates and saves your existing API key.
Cost: Free (signup doesn't consume credits)
Signup with USDC (Base):
# Create signup token with USDC payment method
/botsee signup --crypto
# Start USDC payment (Base mainnet)
/botsee signup-pay-usdc --amount-cents 250 --from-address 0xYOUR_WALLET
# Poll signup status (saves API key on completion)
/botsee signup-statusNetwork:
base-mainnet(Chain ID 8453, production)
Initiate USDC payment for a signup token (POST /api/v1/signup/:token/pay-usdc).
/botsee signup-pay-usdc --token <setup_token> --amount-cents 5000 --from-address 0xYOUR_WALLETOptional:
--payment <proof>x402paymentheader value when retrying after HTTP 402--tx-hash 0x...build transaction-based x402 payload (txHash) automatically--asset USDCasset value for tx-hash payload (default:USDC)
Transaction-hash example:
/botsee signup-pay-usdc --token <setup_token> --amount-cents 5000 --from-address 0xYOUR_WALLET --tx-hash 0xYOUR_TX_HASHCheck signup status and automatically save API key when completed.
/botsee signup-status
/botsee signup-status --token <setup_token>Add credits via USDC on Base (POST /api/v1/billing/topups/usdc).
/botsee topup-usdc --amount-cents 5000 --from-address 0xYOUR_WALLETOptional:
--payment <proof>x402paymentheader value when retrying after HTTP 402--tx-hash 0x...build transaction-based x402 payload (txHash) automatically--asset USDCasset value for tx-hash payload (default:USDC)
Transaction-hash example:
/botsee topup-usdc --amount-cents 5000 --from-address 0xYOUR_WALLET --tx-hash 0xYOUR_TX_HASHCreate site and generate content.
Requires: API key from /botsee signup
/botsee create-site https://example.comThe create-site command will:
- Create a site for the domain
- Generate customer types, personas, and questions
- Save configuration to workspace and user config
Customize generation counts:
/botsee create-site https://example.com --types 3 --personas 2 --questions 10Cost: ~75 credits with defaults (2 types, 2 personas/type, 5 questions/persona) β estimates; actual charges follow LLM token usage
- Site creation: ~5 credits
- Customer types: ~5 credits per type
- Personas: ~5 credits per persona
- Questions: ~10 credits per persona
Save custom configuration for later use with setup.
# With defaults (2/2/5)
/botsee create-site https://example.com
# With custom values
/botsee create-site https://example.com --types 3 --personas 3 --questions 10Saves to .context/botsee-config.json. Setup reads this config automatically.
Display saved workspace configuration.
π BotSee Configuration
βββββββββββββββββββββ
Domain: https://example.com
Customer Types: 2
Personas per Type: 2
Questions per Persona: 5
Ready to run: /botsee setup <domain>
Previews the selected AI visibility analysis for free, showing a planning credit range and measurement warnings. Then starts the analysis, polls until complete, and displays competitors, keywords, and cited sources. A failed preview stops before starting a paid run.
/botsee analyze --dry-run # Preview only; no analysis starts
/botsee analyze --no-persona # Question-only benchmarkPersona context is included by default. Each question/model pair produces one answer, not an average across repeated samples. The credit range is an estimate, not a spending cap.
π Top Competitors:
1. competitor.com - 45 mentions
2. rival.com - 32 mentions
π Top Keywords:
β’ "best email marketing" (12x)
β’ "affordable crm software" (8x)
π Top Sources:
β’ techcrunch.com (5x) β
β’ g2.com (3x)
π° Remaining: 265 credits
Cost: ~660 credits per run (varies by question count and models)
Generates blog post from latest analysis. Auto-saves to botsee-YYYYMMDD-HHMMSS.md.
Cost: 15 credits
List all sites in your account.
/botsee list-sitesView details of a specific site. If uuid is omitted, shows the current site from config.
/botsee get-site
/botsee get-site abc-def-123Create a new site. Saves the new site UUID to config.
/botsee create-site https://example.comCost: 5 credits (auto-generates product_name and value_proposition)
Update a site's metadata. Omitted flags leave that field unchanged.
--aliases is a comma-separated list of brand names, product names, coined phrases, and branded events. BotSee strips these from generated personas and questions so your own terminology doesn't leak into them.
/botsee update-site abc-def-123 --aliases "Acme, Acme Points, ACMECON"
/botsee update-site abc-def-123 --product-name "Acme Points"Cost: Free
Archive a site. If uuid is omitted, archives the current site.
/botsee archive-site
/botsee archive-site abc-def-123List all customer types for the current site.
/botsee list-typesView details of a specific customer type.
/botsee get-type type-uuid-123Create a new customer type manually.
/botsee create-type "Enterprise Buyers" "Large companies seeking solutions"Cost: 5 credits
Generate customer types using AI. Defaults to 2.
/botsee generate-types
/botsee generate-types 3Cost: 5 credits per type
Update a customer type.
/botsee update-type type-uuid-123 --name "Enterprise Decision Makers"
/botsee update-type type-uuid-123 --description "C-level executives"Archive a customer type.
/botsee archive-type type-uuid-123List personas. Show all or filter by customer type.
/botsee list-personas
/botsee list-personas type-uuid-123View details of a specific persona.
/botsee get-persona persona-uuid-456Create a new persona manually.
/botsee create-persona type-uuid-123 "Sarah Chen" "VP of Marketing at mid-sized SaaS"Cost: 5 credits
Generate personas for a customer type using AI. Defaults to 2.
/botsee generate-personas type-uuid-123
/botsee generate-personas type-uuid-123 3Cost: 5 credits per persona
Update a persona.
/botsee update-persona persona-uuid-456 --name "Sarah Chen (CMO)"
/botsee update-persona persona-uuid-456 --description "Chief Marketing Officer"Archive a persona.
/botsee archive-persona persona-uuid-456List questions. Show all or filter by persona.
/botsee list-questions
/botsee list-questions persona-uuid-456View details of a specific question.
/botsee get-question question-uuid-789Create a new question manually.
/botsee create-question persona-uuid-456 "What are the best email marketing tools?"Generate questions for a persona using AI. Defaults to 5.
/botsee generate-questions persona-uuid-456
/botsee generate-questions persona-uuid-456 10Cost: 10 credits per generation call (not per question)
Update a question's text.
/botsee update-question question-uuid-789 "What are the best affordable email marketing tools?"Delete a question permanently.
/botsee delete-question question-uuid-789View competitor analysis results from the latest analysis.
/botsee results-competitorsView keyword analysis results from the latest analysis.
/botsee results-keywordsView source analysis results (which websites cited your site/competitors).
/botsee results-sourcesView all raw AI responses from the latest analysis.
/botsee results-responsesQuestions where your brand is missing or ranks poorly, with per-provider breakdown showing mention rates, rank positions, and exact keywords each AI used.
/botsee results-keyword-opportunities <analysis_uuid>
/botsee results-keyword-opportunities <analysis_uuid> --threshold 0.8
/botsee results-keyword-opportunities <analysis_uuid> --rank-threshold 3--threshold(0.0β1.0, default 1.0): include questions where brand mention rate is below this value--rank-threshold(integer): also flag questions where brand appeared but at a rank worse than this
Sources AI cited in responses where your brand was NOT mentioned β ideal targets for content and link-building.
/botsee results-source-opportunities <analysis_uuid>BotSee skill provides complete CRUD (Create, Read, Update, Delete) operations for all resources:
Sites: List, view, create, and archive sites Customer Types: List, view, create, generate (AI), update, and archive types Personas: List, view, create, generate (AI), update, and archive personas Questions: List, view, create, generate (AI), update, and delete questions
You can:
- Use the high-level
/botsee setupcommand for automatic setup - Or manually build your structure using individual CRUD commands
- View and edit any resource at any time
- Generate additional resources as needed
- Customize your analysis by adding/removing questions
Workspace Config (.context/botsee-config.json):
Saved by /botsee create-site, used by /botsee setup:
{
"domain": "https://example.com",
"types": 2,
"personas_per_type": 2,
"questions_per_persona": 5
}User Config (~/.botsee/config.json):
Saved by /botsee setup with secure permissions (600):
{
"api_key": "bts_live_...",
"site_uuid": "..."
}/botsee setup https://www.example.com
# Output:
π€ BotSee Setup
π Complete signup to get your API key:
https://botsee.io/setup/abc123...
β³ Waiting for signup completion...
β
Signup complete!
Using: 2 types, 2 personas/type, 5 questions/persona
β³ Creating site: https://www.example.com
β
Site created: abc-def-123
β³ Generating 2 customer type(s)...
π Customer Types:
β’ Small Business Owners
β’ Marketing Managers
β³ Generating personas (2 per type)...
β Small Business Owners: 2 persona(s)
β Marketing Managers: 2 persona(s)
β
Generated 4 persona(s)
β³ Generating questions (5 per persona)...
β
Generated 20 question(s)
β
Setup complete!
Generated:
β’ 2 customer type(s)
β’ 4 persona(s)
β’ 20 question(s)
π° Remaining: 925 credits
Next: /botsee analyze/botsee create-site https://www.example.com --types 3 --personas 3 --questions 10
/botsee config-show
/botsee setup https://www.example.com --api-key bts_live_abc123.../botsee analyze
/botsee content# List all personas
/botsee list-personas
# View specific persona
/botsee get-persona persona-uuid-456
# Update persona description
/botsee update-persona persona-uuid-456 --description "Chief Marketing Officer at enterprise SaaS"
# List questions for this persona
/botsee list-questions persona-uuid-456
# Add a new question
/botsee create-question persona-uuid-456 "What are the best alternatives to HubSpot?"# List all customer types
/botsee list-types
# Add a new customer type manually
/botsee create-type "Startup Founders" "Early-stage founders bootstrapping their companies"
# Generate personas for the new type
/botsee generate-personas type-uuid-new 3
# Generate questions for each persona
/botsee list-personas type-uuid-new
/botsee generate-questions persona-uuid-1 10
/botsee generate-questions persona-uuid-2 10
/botsee generate-questions persona-uuid-3 10# After running analysis, view different result types
/botsee results-competitors
/botsee results-keywords
/botsee results-sources
/botsee results-responsesRun a complete AI visibility audit β analyze how AI search engines see a site, identify terminology gaps, and make surgical landing page copy changes.
# 1. Create site with customer types, personas, questions
/botsee create-site https://example.com
# 2. Review and refine auto-generated questions
/botsee list-questions <persona_uuid>
/botsee delete-question <question_uuid>
/botsee create-question <persona_uuid> "What tools help with AI search optimization?"
# 3. Run analysis (~660 credits)
/botsee analyze
# 4. Pull keyword and source opportunities
/botsee results-keyword-opportunities <analysis_uuid>
/botsee results-source-opportunities <analysis_uuid>
# 5. Compare opportunities against live homepage copy
# 6. Make surgical text changes to close terminology gaps
# 7. Compile, verify, and shipTotal cost: ~735 credits (75 setup + 660 analysis) | Time: ~25 min
The /ai-visibility-audit skill automates this entire workflow. Install the plugin to use it.
User Config (~/.botsee/config.json)
- Purpose: Stores API key and site UUID
- Permissions: 0o600 (owner read/write only)
- Created by:
/botsee setupcommand - Contents:
{ "api_key": "bts_live_...", "site_uuid": "abc-def-123" }
Workspace Config (.context/botsee-config.json)
- Purpose: Stores generation defaults (types/personas/questions)
- Permissions: Standard file permissions
- Created by:
/botsee create-sitecommand (optional) - Contents:
{ "domain": "https://example.com", "types": 2, "personas_per_type": 2, "questions_per_persona": 5 }
View current configuration:
/botsee # Show status + API key suffix
/botsee config-show # Show workspace configEdit configuration:
# Workspace config (generation counts)
/botsee create-site <domain> --types 3 --personas 3 --questions 10
# User config (API key + site)
/botsee setup <domain> --api-key <new_key>Manual editing:
- User config: Edit
~/.botsee/config.json(must maintain 0o600 permissions) - Workspace config: Edit
.context/botsee-config.json
Reset configuration:
rm ~/.botsee/config.json # Remove user config
rm .context/botsee-config.json # Remove workspace config
/botsee setup <domain> # Start fresh"Invalid API key"
- Cause: API key expired or incorrect
- Solution: Run
/botsee setup <domain>to create new account or use--api-keywith valid key - Check: API key should start with
bts_live_orbts_test_
"No BotSee config found"
- Cause: Missing
~/.botsee/config.jsonfile - Solution: Run
/botsee setup <domain>to initialize configuration
"Insufficient credits"
- Cause: Account balance too low
- Solution: Use
/botsee topup-usdc --amount-cents 250 --from-address 0x...or add credits at https://botsee.io/billing - Check: Run
/botseeto view current balance
Analysis uses more credits than expected
- Cause: More questions generated than planned
- Check: Run
/botsee list-questionsto count total questions - Solution: Reduce question count or delete unnecessary questions
"HTTP 402 Payment required"
- Cause: Endpoint requires x402 payment proof or account has insufficient credits
- Solution: Top up with
/botsee topup-usdc ...and retry - Optional: Retry USDC payment endpoints with
--payment <proof>to send x402paymentheader
"Connection error"
- Cause: Network connectivity or API downtime
- Solution:
- Check internet connection
- Verify https://botsee.io is accessible
- API calls timeout after 30 seconds - retry for transient errors
"SSL certificate verification failed"
- Cause: Corporate proxy or outdated CA certificates
- Solution: Update system certificates or check proxy settings
Signup times out
- Cause: Didn't complete browser signup within 5 minutes
- Solution: Run
/botsee setup <domain>again to get new signup URL
"Site creation failed"
- Cause: Invalid domain format or duplicate site
- Solution:
- Ensure domain starts with
https:// - Check
/botsee list-sitesfor existing sites - Domain may already be registered to another account
- Ensure domain starts with
Analysis takes too long
- Normal: Analysis can take 5-10 minutes depending on question count
- Timeout: Commands timeout after 10 minutes
- Solution: Reduce number of questions if analysis consistently times out
"No analysis found"
- Cause: Haven't run
/botsee analyzeyet - Solution: Run analysis first, then generate content
Missing analysis UUID
- Cause: Analysis UUID not captured from analyze command output
- Where to find: Look for line
π Analysis started: abc-def-123 - Solution: Re-run
/botsee analyzeand copy the UUID from output
Credit rate: 1 credit = $0.01 USD | Minimum purchase: $20 (2,000 credits) | All CRUD operations are free
- Site creation: 5 credits
- Generate 2 customer types: 10 credits (5 each)
- Generate 4 personas: 20 credits (5 each)
- Generate questions (4 calls): 40 credits (10 per call, not per question)
- Total: ~75 credits
Sites:
- Create site: 5 credits (auto-generates product_name/value_proposition)
Customer Types:
- Create customer type (manual): 5 credits
- Generate customer types (AI): 5 credits per type generated
Personas:
- Create persona (manual): 5 credits
- Generate personas (AI): 5 credits per persona generated
Questions:
- Create question (manual): Free
- Generate questions (AI): 10 credits per API call
- Each call generates multiple questions (default: 5)
- Cost is per generation call, not per question
- Example: Generating 5 questions = 10 credits (one call)
- Example: Generating 10 questions for 4 personas = 40 credits (4 calls, one per persona)
Analysis & Content:
- Analysis (per run): ~660 credits (varies by question count and AI models used)
- Content generation: 15 credits
"Per type" vs "Per call":
-
Per type/persona: Each individual resource costs credits
- Generate 3 types = 15 credits (3 Γ 5)
- Generate 4 personas = 20 credits (4 Γ 5)
-
Per call (questions only): Cost is for the API call, not individual questions
- One call generates multiple questions (you specify count: 3-10)
- Cost: 10 credits regardless of how many questions generated in that call
- Setup calls generate-questions once per persona, so 4 personas = 40 credits (4 calls)
- First complete workflow (setup + analysis + content): ~750 credits
- Add new customer type with 3 personas (10 questions each):
- Create type: 5 credits
- Generate 3 personas: 15 credits
- Generate questions (3 calls): 30 credits
- Total: 50 credits
MIT License - see LICENSE file
- Documentation: https://botsee.io/docs
- Issues: https://github.com/rivalsee/botsee-skill/issues