COMPLIANCE-FIRST AI ENGAGEMENT

Reddit Comment Engagement Agent

AI-powered Reddit engagement with 13-node LangGraph workflow, quality scoring, human-in-the-loop approval, and comprehensive safety controls

Version 2.5136 Tests Passing13-Node PipelineProduction Ready
← Back to Projects

Overview

The Reddit Comment Engagement Agent is an intelligent automation tool that helps you engage with Reddit communities while maintaining compliance and avoiding shadowbans. Built with a compliance-first approach, it uses AI to identify high-quality engagement opportunities and requires human approval before posting.

Perfect for developers, marketers, and community managers who want to maintain authentic Reddit presence without manual monitoring. The agent operates within strict safety limits and learns from historical performance to improve over time.

Use Cases

Product Promotion

Engage authentically when users ask about your product category

Community Support

Respond to questions in your niche with helpful answers

Content Distribution

Share relevant blog posts or resources where appropriate

Key Features

AI-Powered Quality Scoring

7-factor quality assessment including upvote ratio, author karma, content freshness, engagement velocity, question signals, thread depth, and historical performance.

Human-in-the-Loop Approval

Mandatory approval via Slack/Telegram with URL-based buttons. Secure one-time tokens with 48-hour expiry ensure safety. Auto-publish after approval.

Shadowban Protection

Daily limits (8 comments/day), cooldown periods, random timing jitter, bot filtering, and diversity controls prevent detection and shadowbans.

LangGraph Workflow

13-node pipeline with intelligent routing: fetch candidates → score quality → filter duplicates → check compliance → human approval → auto-publish.

Historical Learning

Learns from past performance per subreddit with time-decay weighting. Tracks 24-hour engagement metrics (upvotes, replies) to refine future scoring.

Web Dashboard

Next.js admin UI with real-time stats, settings editor, workflow visualizer, and setup wizard. Secure JWT authentication with role-based access.

Architecture

Backend Stack

  • FastAPI - High-performance Python web framework with async support
  • LangGraph - Orchestrates 13-node workflow with conditional logic
  • PostgreSQL - Persistent storage with Alembic migrations
  • PRAW - Reddit API wrapper with rate limiting
  • Gemini 2.5 Flash - Primary LLM for draft generation

Frontend Stack

  • Next.js 16 - React framework with App Router
  • shadcn/ui - Beautiful Radix UI components
  • TypeScript - Type-safe development
  • Tailwind CSS - Utility-first styling
  • Recharts - Data visualization for dashboard

How It Works

13-Node LangGraph Workflow
Intelligent pipeline with quality-driven candidate selection
  1. 1

    Fetch Candidates

    Retrieves inbox replies (HIGH priority) + rising posts/comments from allowed subreddits

  2. 2

    Select by Ratio

    Applies 30% post / 70% comment distribution for natural engagement patterns

  3. 3

    Score Quality

    AI-powered 7-factor scoring with historical learning and 25% exploration

  4. 4

    Filter & Check Rules

    Removes duplicates, applies cooldowns, verifies subreddit compliance

  5. 5

    Diversity Select

    Max 2 per subreddit, max 1 per post (with quality overrides)

  6. 6

    Generate Draft

    LLM creates human-like reply with context-aware prompts

  7. 7

    Human Approval

    Sends to Slack/Telegram with approve/reject buttons + context link

  8. 8

    Auto-Publish

    Posts approved drafts to Reddit automatically with random timing jitter

Getting Started

Prerequisites
  • Python 3.11+ installed
  • Reddit API credentials (Client ID + Secret)
  • LLM API key (Gemini, OpenAI, or Anthropic)
  • PostgreSQL database (local or cloud)
  • Public URL for callback server (ngrok, Cloudflare Tunnel, or VPS)
Installation

1. Clone the repository

bash
git clone https://github.com/yourusername/reddit_agent
cd reddit_agent

2. Create virtual environment

bash
python -m venv venv
source venv/bin/activate  # macOS/Linux
# OR
venv\Scripts\activate  # Windows

3. Install dependencies

bash
pip install -r requirements.txt

4. Configure environment

bash
cp .env.example .env
# Edit .env with your credentials

5. Run database migrations

bash
alembic upgrade head

6. Start the callback server

bash
python main.py server

7. Run the agent (in another terminal)

bash
source venv/bin/activate
python main.py run --once

Configuration Guide

Reddit API Setup
  1. 1. Visit reddit.com/prefs/apps
  2. 2. Click "Create App" or "Create Another App"
  3. 3. Select "script" type
  4. 4. Fill name and redirect URI (http://localhost)
  5. 5. Copy Client ID (under app name) and Secret
  6. 6. Add to .env file
LLM API Keys

  • Gemini (Recommended)

    Get free API key at aistudio.google.com

  • OpenAI

    Sign up at platform.openai.com

  • Anthropic

    Get API key from console.anthropic.com

Notification Setup

  • Slack Webhook

    Create incoming webhook at api.slack.com/apps

  • Telegram Bot

    Create bot via @BotFather, get token + chat ID

  • Generic Webhook

    Any endpoint accepting POST with JSON payload

Safety Limits
  • MAX_COMMENTS_PER_DAY8
  • MAX_COMMENTS_PER_RUN3
  • INBOX_COOLDOWN_HOURS6
  • RISING_COOLDOWN_HOURS24
  • POST_REPLY_RATIO0.3

Web Dashboard

Features

  • Dashboard Stats

    Real-time metrics, charts, and draft status

  • Settings Editor

    Edit environment variables with validation

  • Workflow Visualizer

    Interactive 13-node pipeline diagram

  • Setup Wizard

    4-step configuration with test functions

Access

bash
# Start server (includes web dashboard)
python main.py server

# Access dashboard
# Open browser: http://localhost:3000

Default password: admin123

Change password hash in .env: ADMIN_PASSWORD_HASH

Frequently Asked Questions

Related Projects

AI Integration
Jenkins MCP Server
Enable AI agents to interact with Jenkins through Model Context Protocol
Learn More →
CRM Integration
Method CRM MCP
Production-ready MCP server for Method CRM API with 20 tools
Learn More →
Production SaaS
Social Media Auto-Poster
AI-powered platform with automated posting and multi-platform support
Learn More →

License & Credits

License

This project is available under an open-source license. See the repository for full license details.

Author: Avinash Sangle
Website: avinashsangle.com
Year: 2026

Built With

  • • LangGraph - Workflow orchestration
  • • PRAW - Reddit API wrapper
  • • FastAPI - High-performance web framework
  • • shadcn/ui - Beautiful React components
  • • PostgreSQL - Reliable database
  • • Gemini 2.5 Flash - AI language model
  • • Built with Claude Code - AI-assisted development

Ready to Get Started?

Start engaging with Reddit communities intelligently while maintaining compliance and avoiding shadowbans.

← Back to Projects