🔥 Ember

Modular. Modern. Production-ready Discord bot framework.

Overview • Cogs • Quick Start • Docker • Extras • Development • Credits

---

Overview

Ember is a fully modular Discord bot built on discord.py 2.4+ and Components V2. Every feature is a self-contained cog — enable or disable anything without touching the core. It ships with a real permissions framework, per-guild config, a central modlog, and a service-layer architecture that keeps business logic testable and clean.

Inspired by Red-DiscordBot's battle-tested patterns, built clean from scratch with modern Python and async-first design.

The default cog set includes:

• Moderation (warn, mute, ban, kick, modlog with case cards)
• Community tools (birthdays, AFK, booster roles, welcome messages, activity roles)
• Utility (temp voice channels, thread cleaner, custom commands, channel management)
• Fun (game pings, emoji stealer, general commands)
• Economy (bank, credits)
• Integrations (Twitch streams, GitHub→Discord, DuckDNS, backups)

Extra plugins (privacy-sensitive features, shipped separately in Ember-extras):

• Confessions — anonymous confession system with replies and mod tools
• ShadowChat — anonymous gender-matched chat roulette with DM relay

---

Cogs

admin — Bot management and configuration

Cog	Description
cleanup	Bulk message deletion and channel pruning
cog_manager	Load, unload, and reload cogs at runtime
dev	Developer utilities and debug commands
downloader	Install cogs from external repositories
permissions_mgr	Fine-grained per-guild permission overrides
settings	Bot-wide and per-guild configuration panel

community — Engagement and social features

Cog	Description
activity_roles	Auto-assign roles based on game activity
afk	AFK status with auto-mention suppression
birthday	Birthday tracking, announcements, and role assignment
booster_roles	Custom colour roles for server boosters
promoter	Self-promotion channel with cooldown management
welcome	Configurable welcome embeds and DMs for new members

mod — Moderation and logging

Cog	Description
moderation	Warn, mute, kick, ban, softban with case tracking
modlog	Central moderation log with sequential case cards
bot_logging	Audit log mirroring and event logging
branding	Server branding enforcement and asset management
filter	Word/phrase filter with configurable actions
reports	User report system with staff escalation

utility — Quality-of-life tools

Cog	Description
channels	Channel lock/unlock and management shortcuts
customcom	Custom slash commands with variable substitution
dragme	Move users between voice channels
feedback	Structured feedback collection with staff routing
multi_lounge	Multiple persistent lounge channels
nick	Server-wide nickname management
rolementions	Temporarily mentionable role toggle
status	Rotating bot status messages
tempvc	Dynamic temporary voice channel creation
thread_cleaner	Auto-archive or delete inactive threads

fun — Entertainment

Cog	Description
emoji_stealer	Steal and add emojis from other servers
game_ping	Game-activity-based role ping system
general	Miscellaneous fun commands
ping	Latency check with gateway and API round-trip

economy — Virtual currency

Cog	Description
bank	Virtual bank with credits, transfers, and leaderboard

integrations — External service connectors

Cog	Description
backups	Automated database backups to Backblaze B2
duckdns	DuckDNS IP updater for dynamic DNS
reconnect	Auto-reconnect watchdog for gateway drops
streams	Twitch live-stream alerts

---

Quick Start

Prerequisites

• Python 3.11 or higher
• A Discord bot token — create one at the Developer Portal
• Enable Message Content, Server Members, and Presence intents

Install

git clone https://github.com/guardiansofspartax/Ember.git
cd Ember
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Edit .env — at minimum, set BOT_TOKEN:

BOT_TOKEN=your_discord_bot_token_here

# Optional but recommended
OWNER_IDS=111111111111111111
GUILD_ID=123456789012345678        # dev guild for instant slash command sync
EMBER_DB_BACKEND=sqlite            # sqlite | postgres | mongo

Run

python main.py          # load all cogs
python main.py birthday # load one cog (dev/debug)

On first start, slash commands sync to your dev guild instantly. Global sync takes up to one hour.

---

Docker

# Production
docker compose --profile production up -d

# Development (code mounted, auto-reload)
docker compose --profile development up

See docs/DEPLOYMENT.md for full Docker, PM2, and systemd deployment guides.

---

Plugins

Privacy-sensitive cogs live in the separate Ember-extras repository so the core stays clean and auditable.

Install a plugin:

# Clone extras next to Ember
git clone https://github.com/guardiansofspartax/Ember-extras.git ../Ember-extras

# Symlink (or copy) the plugin into cogs/
ln -s ../../Ember-extras/confessions cogs/community/confessions

Then restart the bot — Ember's auto-loader will pick it up.

---

Development

make install        # create venv + install all deps
make pre-commit     # install git hooks

make lint           # ruff + black + mypy
make test           # pytest
make test-cov       # pytest with coverage report
make security       # bandit + pip-audit + safety
make dev-checks     # everything above together

Adding a Cog

cogs/<category>/<cog_name>/
├── __init__.py    # async setup(bot)
├── cog.py         # EmberCog subclass with commands
└── service.py     # business logic (optional, recommended)

from discord import app_commands
from core.cog import EmberCog
from core.permissions import PermissionLevel, requires

class MyCog(EmberCog):
    @app_commands.command(name="hello", description="Say hello")
    @requires(PermissionLevel.USER)
    async def hello(self, interaction: discord.Interaction) -> None:
        await self.send_success(interaction, f"Hey, {interaction.user.mention}!")

async def setup(bot):
    await bot.add_cog(MyCog(bot))

See docs/COG_CONTRIBUTION.md for the full guide and docs/FRAMEWORK_API.md for the API reference (Store, cards, errors, checks, modlog, bank, i18n, formatting).

---

Project Structure

Ember/
├── cogs/                  # All bot extensions (auto-discovered)
│   ├── admin/
│   ├── community/
│   ├── economy/
│   ├── fun/
│   ├── integrations/
│   ├── mod/
│   └── utility/
├── core/                  # Framework internals
│   ├── bot.py             # EmberBot — subclasses discord.ext.commands.Bot
│   ├── cog.py             # EmberCog base class
│   ├── database.py        # Multi-backend DatabaseManager (sqlite/pg/mongo/json)
│   ├── permissions.py     # @requires() decorator + PermissionLevel enum
│   ├── modlog.py          # Central moderation logging
│   ├── rpc.py             # JSON-RPC 2.0 server (optional)
│   └── errors.py          # Exception hierarchy
├── utils/                 # Shared helpers
│   ├── cards.py           # LayoutView card builders (Components V2)
│   ├── views.py           # Reusable UI views
│   └── validators.py      # Input validation utilities
├── config/                # Environment and startup config
├── docs/                  # Guides and architecture docs
├── scripts/               # CLI utilities (ember.py, dev_utils.py)
├── test/                  # Test suite
├── main.py                # Entry point
├── Dockerfile
├── docker-compose.yml
└── .env.example

---

Credits

Ember is built on the shoulders of giants:

• discord.py by Rapptz — the async Discord library powering everything
• Red-DiscordBot by the Cog Creators team — architectural inspiration for the cog system, permissions model, and modlog design
• Pycord — reference for Components V2 UI patterns

---

License

Released into the public domain under the Unlicense.

---

Support

• Issues: GitHub Issues
• Discord: The Aakhri Station
• Docs: docs/