Lead Tracking

• Every replied post analyzed by Claude for customer potential
• Scored 1–10 with urgency level
• Extracts business type and pain points
• View with: social reply bot leads

Configuration

Edit ~/social-bot/config.json to set your subreddits, X search queries, product descriptions, and daily targets.

How It Works

Keyword Search (Reddit subreddits + X queries)
       ↓
Two-Layer Relevance Filter
  ├─ Layer 1: Keyword match (zero API cost)
  └─ Layer 2: Claude AI judges if post is worth replying to
       ↓
Claude generates reply as "experienced seller sharing real insight"
       ↓
Browser automation posts the reply
       ↓
SQLite logs it → Dashboard displays it → Lead scored

The core principle: Every reply must provide genuine value. The AI is prompted as a "seller with 5 years of experience" who naturally mentions tools they use — not as a marketer pushing a product. Posts that don't fit get skipped, not force-fitted.

Screenshots

Dashboard — Real-time Daily Progress

The web dashboard tracks daily X posts, Reddit comments, product mentions, and historical totals.

X/Twitter — Targeted Competitive Replies

The bot found a competitor's tweet about customer support automation and replied with a genuine insight that naturally positioned Solvea as an alternative. No "Great product!" fluff — real technical substance.

Reddit — High-Quality Community Comments

On r/ecommerce, a user discussed WooCommerce chatbot inventory sync issues. The bot shared specific technical experience (event-triggered vs. scheduled sync), earning genuine upvotes and discussion.

Quick Start

Option 1: One-Line Install

curl -fsSL https://raw.githubusercontent.com/mguozhen/social-bot/main/install.sh | bash

This will:

1. Clone the repo to ~/social-bot
2. Install Python dependencies (anthropic, flask)
3. Check for browse CLI
4. Guide you through .env setup
5. Initialize SQLite database
6. Register macOS LaunchAgent (daily 10:05 AM)

Option 2: Manual Setup

git clone https://github.com/mguozhen/social-bot.git ~/social-bot
cd ~/social-bot
pip3 install -r requirements.txt
cp .env.template .env
# Edit .env with your ANTHROPIC_API_KEY

Prerequisites

| Requirement | How to Get It | |------------|---------------| | Python 3.9+ | Pre-installed on macOS | | browse CLI | npm install -g @anthropic-ai/browse-cli | | Anthropic API Key | console.anthropic.com | | Reddit account | Log in once in the browse-controlled Chrome | | X/Twitter account | Log in once in the browse-controlled Chrome |

No Reddit API key or Twitter API key required. The bot uses browser sessions, not platform APIs.

Commands

As Claude Code Skill

Once installed as a skill, just tell Claude:

social reply bot                  # run both platforms
social reply bot x only           # X/Twitter only
social reply bot reddit only      # Reddit only
social reply bot warmup           # build Reddit karma (8 comments)
social reply bot warmup 15        # warmup with custom target
social reply bot leads            # show potential customers found
social reply bot stats            # today's stats
social reply bot dashboard        # open web dashboard

As Standalone Script

python3 run_daily.py              # run both platforms
python3 run_daily.py --x-only     # X only
python3 run_daily.py --reddit-only # Reddit only
python3 warmup_reddit.py          # karma building mode

Configuration

Edit config.json to customize for your product:

{
  "x": {
    "username": "@YourAccount",
    "daily_target": 20,
    "min_delay_seconds": 300,
    "search_queries": [
      "your product keyword 1",
      "your product keyword 2"
    ]
  },
  "reddit": {
    "username": "your_reddit_user",
    "daily_target": 10,
    "min_delay_seconds": 600,
    "subreddits": ["YourTargetSubreddit", "AnotherOne"]
  },
  "products": {
    "YourProduct": {
      "description": "What your product does (AI uses this to craft mentions)",
      "trigger_keywords": ["keyword1", "keyword2"]
    }
  },
  "reply_style": {
    "tone": "knowledgeable practitioner sharing experience",
    "max_length_x": 260,
    "max_length_reddit": 400,
    "rules": [
      "Lead with genuine insight about the post",
      "Mention product as 'what we use/built' — not as an ad",
      "Skip if not relevant — never force a mention"
    ]
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ANTHROPIC_API_KEY | Yes | Claude API key for reply generation | | BROWSERBASE_API_KEY | No | Optional: persistent browser sessions across reboots | | BROWSERBASE_PROJECT_ID | No | Optional: pairs with Browserbase key |

Architecture

social-bot/
├── bot/
│   ├── ai_engine.py        # Claude AI: relevance filter + reply generation
│   ├── browser.py           # Browser automation via browse CLI
│   ├── db.py                # SQLite: dedup, history, lead scoring
│   ├── reddit_bot.py        # Reddit: search subreddits, post comments
│   └── x_bot.py             # X/Twitter: search queries, post replies
├── dashboard/
│   ├── app.py               # Flask web dashboard
│   └── templates/           # Dashboard HTML
├── docs/
│   ├── screenshot_dashboard.png
│   ├── screenshot_reddit_reply.png
│   └── screenshot_x_reply.png
├── launchd/                 # macOS LaunchAgent plist
├── config.json              # Platform targets, keywords, products
├── run_daily.py             # Main entry point (scheduled daily)
├── warmup_reddit.py         # Reddit karma builder
├── install.sh               # One-line installer
├── setup.sh                 # Manual setup helper
├── SKILL.md                 # Claude Code / Agent Skills definition
└── .env.template            # Credential template

Two-Layer Filtering

# Layer 1: Fast keyword match (zero API cost)
def detect_product(text: str) -> Optional[str]:
    # Returns matching product name or None

# Layer 2: Claude AI relevance check
# If Layer 1 matches, Claude decides:
#   - Is this post genuinely relevant?
#   - Can we add real value with a reply?
#   - SKIP if forcing a mention would feel unnatural

Rate Limiting & Safety

| Platform | Delay Between Replies | Daily Cap | Deduplication | |----------|----------------------|-----------|---------------| | Reddit | 10 minutes | 10 posts | SQLite (URL-based) | | X/Twitter | 5 minutes | 20 posts | SQLite (URL-based) |

Reddit Warmup

New Reddit accounts need karma before posting in restricted subreddits. The warmup mode:

• Visits safe, low-moderation subreddits (r/karma, r/CasualConversation, r/self)
• Claude Haiku generates authentic short comments (no product mentions)
• 90-180 second natural delays between posts
• Default: 8 comments per session, configurable

p