An intelligent Discord moderation bot that combines fast pattern matching with LLM reasoning to protect your community. Learns from your server's rules and gets smarter over time.
- PostgreSQL Database (Supabase, Railway, Heroku, or self-hosted)
- OpenAI API Key from platform.openai.com (configured after bot starts)
- Discord Bot Token with Message Content and Server Members intents enabled
# Install dependencies
uv sync
# Create .env file with required variables
cat > .env << EOF
DISCORD_TOKEN=your_discord_bot_token
DATABASE_URL=postgresql://user:password@host:5432/database
EOF
# Run the bot
uv run python main.py- Invite bot to server with required permissions (see docs)
- Configure LLM credentials (stored in database, not environment variables):
/set-llm api_key:sk-proj-your-key model:gpt-4o-mini - Add your rules channel as context:
/add-channel channel:#rules description:Server rules and guidelines - Wait 30 seconds for the bot to:
- Read and understand your rules
- Generate server-specific heuristics
- Prepare for moderation
- Test in dry-run mode (optional):
/set-dry-run enabled - Start moderating - The bot now monitors messages based on YOUR server's rules!
Important: The bot learns moderation patterns from the context channels you provide. Point it at channels containing your server rules, guidelines, and community standards.
- Hybrid Moderation: Fast pattern matching + LLM reasoning for complex decisions
- Self-Learning: Generates server-specific heuristics from your rules
- Context-Aware: References your server's channels for decisions
- Natural Conversations: Hold conversations, answer questions, assist users
- Automatic Threading: Creates threads in busy channels
- Comprehensive Logging: Full audit trail in database + logs channel
- Dry-Run Mode: Test before enforcement
- Global Fraud Detection: 25+ pre-seeded scam patterns (Nitro scams, phishing, etc.)
- Prompt Injection Protection: Automatic detection and prevention of manipulation attempts
- Fast Path: Checks messages against heuristics (<10ms)
- Smart Path: LLM analyzes complex cases (~500-1500ms)
- Learning: Generates new patterns from your rules and feedback
- Actions: Deletes, warns, timeouts, kicks, or bans as needed
- Architecture Overview - System design and components
- Configuration Guide - All settings and commands
- Heuristics System - Pattern matching and learning
- Prompt Injection Protection - Security against manipulation
- Database Schema - Data structure and queries
- Deployment Guide - Production deployment
/add-channel Add a context channel (rules, guidelines, etc.)
/set-persona Customize bot personality
/set-logs-channel Set moderation logs channel
/add-memory Add persistent instruction
/set-dry-run Toggle test mode
/list-heuristics View learned patterns
Context Menu:
- Right-click message → "Flag for Moderation" to teach the bot
# Admin adds rules channel
/add-channel channel:#rules description:Server rules and guidelines
# Bot reads channel, finds rules like:
# "1. No spam or advertising"
# "2. No hate speech or slurs"
# "3. Be respectful to all members"
# Bot generates heuristics:
✅ Pattern: "discord\.gg/[a-z0-9]+" (spam detection)
✅ Pattern: "f4g" (hate speech, fuzzy match)
✅ Generated 12 heuristics from #rules
User: "Free Nitro here! discord.gg/scam123"
# Bot processes:
1. Matches heuristic: "free nitro" (confidence: 0.95)
2. Matches heuristic: "discord.gg/*" (confidence: 0.80)
3. LLM analyzes: "This is a Nitro scam violating Rule #1"
4. Action: Delete message, warn user, log event
🤖 Sentinel: @User, your message was removed. Our server prohibits spam and scam links. Please review #rules.
# Admin flags a message that slipped through
Right-click message → "Flag for Moderation"
Reason: "This violates our no self-promotion rule"
# Bot learns:
✅ Analyzed message pattern
✅ Generated new heuristic
✅ Will catch similar messages in the future
- Python 3.10+
- PostgreSQL 12+ (any provider)
- Discord Bot with privileged intents:
- ✅ Server Members Intent
- ✅ Message Content Intent
- OpenAI API Key (or compatible provider)
| Variable | Required | Description |
|---|---|---|
DISCORD_TOKEN |
Yes | Bot token from Discord Developer Portal |
DATABASE_URL |
Yes | PostgreSQL connection string |
HEALTH_HOST |
No | Health check host (default: 0.0.0.0) |
HEALTH_PORT |
No | Health check port (default: 8080) |
Note: LLM credentials (API key, model, base URL) are stored in the database and configured using the /set-llm slash command, not environment variables.
Deploy to any platform supporting Python + PostgreSQL:
- Fly.io (recommended): See Deployment Guide
- Heroku: Works with Heroku Postgres
- Railway: One-click PostgreSQL integration
- Docker:
docker-compose.ymlincluded - VPS: Systemd service file example in docs
Health Check Endpoint: http://your-host:8080/health
Typical usage with GPT-4o-mini:
- Small server (10,000 messages/month): ~$5-10/month
- Medium server (50,000 messages/month): ~$20-40/month
- Large server (200,000 messages/month): ~$80-150/month
Cost optimization:
- Heuristics reduce LLM calls by 50-80%
- Use
gpt-4o-mini(10-20x cheaper than GPT-4) - Disable proactive moderation for low-risk channels
┌─────────────────────────────────────────────┐
│ Discord Message Event │
└────────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Check Heuristics (Fast Path) │
│ • Regex patterns │
│ • Exact/fuzzy word matching │
│ • Global fraud patterns │
└────────────────┬────────────────────────────┘
│
┌────────┴────────┐
│ Match Found? │
└────────┬────────┘
│ Yes
▼
┌─────────────────────────────────────────────┐
│ LLM Reasoning (Smart Path) │
│ • Analyzes context │
│ • Reviews server rules │
│ • Decides proportional action │
└────────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Execute Action & Learn │
│ • Delete/warn/timeout/kick/ban │
│ • Log to database │
│ • Generate new heuristics │
└─────────────────────────────────────────────┘
See CONTRIBUTING.md for guidelines.
MIT License - see LICENSE
- Issues: GitHub Issues
- Documentation: See
docs/directory - Security: Report vulnerabilities privately to maintainers
Need help getting started? Check out the Configuration Guide for detailed setup instructions.