mguozhen/social-bot

Social Reply Bot

AI-powered Reddit & X auto-reply bot that finds your customers and joins the conversation.

Quick Start • How It Works • Features • Screenshots • Configuration • Architecture

---

What is this?

Social Reply Bot searches Reddit and X/Twitter for posts relevant to your product, then uses Claude AI to generate genuine, helpful replies that naturally mention your brand. No API keys for Reddit or X required — it uses browser automation to act like a real user.

Not spam. The AI evaluates every post for relevance first. If a post isn’t a good fit, it skips it. When it does reply, it sounds like an experienced practitioner sharing real insight — because that’s what the prompt engineers it to be.

Currently configured for two products:

• Solvea — AI customer service agent for Amazon/Shopify sellers
• VOC.ai — Amazon review intelligence and sentiment analysis

But it’s fully configurable for any product/niche via config.json.

Features

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

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

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

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

python3 warmup_reddit.py          # default 8 comments
python3 warmup_reddit.py --target 15  # custom target

Expected Results

With default settings (X: 20/day, Reddit: 10/day):

This isn’t viral growth — it’s consistent, targeted brand presence in conversations where your product is genuinely relevant.

Known Limitations

FAQ

Contributing

PRs welcome. Please test your changes with both platforms before submitting.

License

MIT

---

Built with Claude AI • Browser automation via browse CLI