View on GitHub

Cogs Overview

Cogs are modular components that let you organize your Discord bot’s features into separate, manageable files.
With BotBox, cogs are first-class citizens—easy to add, remove, and maintain.

What is a Cog?

A cog is a Python class that groups related commands and event listeners.
Each cog lives in its own file under src/cogs/.

Why Use Cogs?

  • Separation of concerns: Keep features isolated and code clean.
  • Easy to add/remove: No need to edit your main bot file for every new feature.
  • Dynamic loading: Enable, disable, or reload cogs at runtime.

Command Types

A cog can hold three kinds of command.

TypeInvoked byNotes
slash/nameArguments are typed inline
prefix!nameUses your bot's command prefix
modal/nameOpens a Discord popup form with up to five text inputs, see Modal Commands

Slash and modal commands are both app commands, so both live in the slash_commands array in botbox.conf.

How BotBox Manages Cogs

  • Add a cog:
    Run botbox add and follow the prompts.
    BotBox will generate a new file in src/cogs/ and update botbox.conf.

  • Remove a cog:
    Run botbox remove to safely delete a cog and update your config.

  • Sync cogs:
    If you add/remove cogs manually, run botbox config sync to update botbox.conf.

📝 NOTE
Cogs are loaded dynamically at runtime based on their env field in botbox.conf and the ENVIRONMENTS variable in your environment.
  • Only cogs whose env matches a value in ENVIRONMENTS will be loaded.
  • This allows you to have development-only cogs, or hide unfinished features in production.

Example: A Simple Cog

python
import discord
from discord.ext import commands

class HelloWorld(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

    @commands.command()
    async def hello(self, ctx):
        """Responds with 'world'."""
        await ctx.send("world")

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

Cog Registration

BotBox automatically registers cogs listed in botbox.conf.
When your bot starts, it loads all cogs whose env matches the current environment.

Managing Cogs at Runtime

The cogs.py file in src/cogs/ provides slash commands for:

  • Reloading a cog
  • Reloading all cogs
  • Listing available cogs
  • Loading/unloading cogs

Next Steps