GuardDen/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

GuardDen is a minimal, cost-conscious Discord moderation bot focused on spam detection and NSFW image filtering. Built with discord.py, PostgreSQL, and optional AI integration (Claude/OpenAI) for image analysis only. Self-hosted with Docker support.

Commands

# Install dependencies
pip install -e ".[dev,ai]"

# Run the bot
python -m guardden

# Run tests
pytest

# Run single test
pytest tests/test_automod.py::TestAutomodService::test_spam_detection

# Lint and format
ruff check src tests
ruff format src tests

# Type checking
mypy src

# Docker deployment
docker compose up -d

# Database migrations
alembic upgrade head

Architecture

• src/guardden/bot.py - Main bot class (GuardDen) extending commands.Bot, manages lifecycle and services
• src/guardden/config.py - Pydantic settings loaded from environment variables (prefix: GUARDDEN_)
• src/guardden/models/guild.py - SQLAlchemy 2.0 async models for guilds and settings
• src/guardden/services/ - Business logic (database, guild config, automod, AI, rate limiting)
• src/guardden/cogs/ - Discord command groups (automod, ai_moderation, owner)
• config.yml - Single YAML file for bot configuration

Key Patterns

• All database operations use async SQLAlchemy with asyncpg
• Guild configurations loaded from single config.yml file (not per-guild)
• Discord snowflake IDs stored as BigInteger in PostgreSQL
• No moderation logging or strike system
• Environment variables: GUARDDEN_DISCORD_TOKEN, GUARDDEN_DATABASE_URL, AI keys

Automod System

• AutomodService in services/automod.py handles spam detection
• Checks: message rate limit → duplicate messages → mass mentions
• Spam tracking uses per-guild, per-user trackers with automatic cleanup
• Results return AutomodResult dataclass with actions to take
• Everyone gets moderated (no whitelist, no bypass for permissions)

AI Moderation System

• services/ai/ contains provider abstraction and implementations
• AIProvider base class defines interface: analyze_image() only
• AnthropicProvider and OpenAIProvider implement the interface
• NullProvider used when AI is disabled (returns empty results)
• Factory pattern via create_ai_provider(provider, api_key)
• ImageAnalysisResult includes NSFW categories, severity, confidence
• Sensitivity setting (0-100) adjusts thresholds
• NSFW-Only Filtering (default: True): Only sexual content is filtered
• Cost Controls: Rate limiting, deduplication, file size limits, max images per message
• AIRateLimiter in services/ai_rate_limiter.py tracks usage

Adding New Cogs

1. Create file in src/guardden/cogs/
2. Implement setup(bot) async function
3. Add cog path to _load_cogs() in bot.py

Adding New AI Provider

1. Create src/guardden/services/ai/newprovider.py
2. Implement AIProvider abstract class
3. Add to factory in services/ai/factory.py
4. Add config option in config.py