OpenModBot

OpenModBot is a Discord moderation bot for text channels. It provides core AI-assisted message moderation, per-server watchlists, karma and review queues, optional automod actions, and a plugin system for storage, AI providers, admin notifications, telemetry, rewrite personalities, and passive harassment analysis.

Experimental status: OpenModBot is a large experiment in vibe coding and AI-assisted moderation tooling. Review the code, configuration, permissions, and moderation behavior carefully before using it in a real community, especially before enabling deletion, timeout, kick, ban, or content-retention features. Use it at your own risk; the maintainer does not accept responsibility for damage, data loss, moderation mistakes, community disputes, or other liabilities resulting from use of this project.

Highlights

• Deletes AI-flagged messages and rewrites flagged watchlist messages in a more constructive tone.
• Tracks per-server watchlists, karma scores, capped karma history, and moderation review queues.
• Supports shadow mode for reviewing would-be moderation actions before enforcing them.
• Uses in-memory moderation state by default, with optional Redis or Postgres-backed storage.
• Supports OpenAI by default and Gemini through the optional google_ai plugin.
• Provides optional plugins for harassment insights, admin notifications, telemetry, and rewrite personalities.

Quick Start

Requirements:

• Ruby 3.3.11
• Bundler 2.4.5 or newer
• Discord bot token
• OpenAI API key, or Google AI API key when using PLUGINS=google_ai

Install dependencies:

gem install bundler -v 2.4.5
bundle install

Create .env from .env.sample and fill in at least:

DISCORD_BOT_TOKEN=my_discord_secret
OPENAI_API_KEY=my_openai_secret

Run the bot:

bundle exec ruby bot.rb

Run tests and lint:

bundle exec rspec
bundle exec rubocop

Common Configurations

Use the default in-memory storage for local testing:

PLUGINS=

Use Redis-backed core moderation state:

bundle config set --local with redis
bundle install
PLUGINS=redis
REDIS_URL=redis://localhost:6379/0

Use Postgres-backed core moderation state:

bundle config set --local with postgres
bundle install
PLUGINS=postgres
DATABASE_URL=postgres://postgres:postgres@localhost:5432/openmodbot

Enable passive harassment insights:

bundle config set --local with postgres
bundle install
PLUGINS=postgres,harassment
DATABASE_URL=postgres://postgres:postgres@localhost:5432/openmodbot

Enable admin notifications:

PLUGINS=admin_notifications
ADMIN_NOTIFICATION_CHANNEL_ID=123456789012345678

Documentation

The GitHub wiki carries the operator-facing documentation:

• Home
• Getting Started
• Configuration
• Moderation Commands
• Plugins
• Operations
• Development

Repository docs cover design and implementation details:

• Architecture
• Data model
• Architecture decision records
• Harassment Postgres cutover

Built-In Plugins

• openai
• google_ai
• redis
• postgres
• harassment requires postgres
• admin_notifications
• telemetry
• personality

External plugins can follow the OpenModBot::Plugin hook interface and register with OpenModBot::PluginRegistry.register.