tnoff Discord Bot

A discord bot framework written in python. Supports starting a bot via a token, configuration via YAML files, database sessions, and includes plugin support.

Includes some pre-written cogs for:

• Playing audio from YouTube and other media sites in voice channels
• Looking up words in Urban Dictionary
• Auto generating messages from channel history via Markov Chains
• Auto deletion of messages in specific channels
• Advanced Role Based Access Control

Setup

This project is made up of seven pods that work together; assume all seven are built and running — see docs/setup.md for the full walkthrough. Docker Compose is the quickest way to stand up the whole stack:

$ git clone https://github.com/tnoff/discord-bot.git
$ cd discord-bot
$ cp docker/.env.example docker/.env      # Discord token + music creds; leave MULLVAD_* blank
$ docker compose -f docker/docker-compose.multiprocess.yml --profile local up -d --build

Installing just the bot's own package via pip is not recommended — with seven inter-dependent pods, standing up the rest of the stack by hand is significantly more work than Compose does for you.

Configuration

Each of the seven pods takes its own YAML config file — there is no single config that runs "the bot" by itself. Only the bot and dispatcher pods require a real Discord bot token (generate one via the discord developer portal) — the bot for its gateway connection, the dispatcher to authenticate outbound REST calls; the other five pods don't need one. Every pod's config supports pyaml-env so values can come from an environment variable instead of being written in plain text. See docs/configuration.md for the full per-pod configuration reference — database, logging, cog include-list, intents, guild-removal — and the Monitoring Documentation for OpenTelemetry setup.

Help Page

To check the available functions, use !help command.

Cogs

The gateway only parses commands. !hello, !roll, !meta, !urban, the !markov commands and the store-only !playlist commands (create, list, show, delete, rename, item-remove, merge) are forwarded to the discord-commands pod, which runs them and replies through the dispatcher; the rest still run in the gateway while they move across one group at a time (see HA architecture).

CommandErrorHandler loads unconditionally and has no user-facing commands. MessageDispatcher is not one of the bot's cogs at all — it is the sole worker of the separate discord-dispatcher pod, which sends and edits Discord messages on the bot's behalf over HTTP. See Message dispatcher.

Additional docs

• Setup — the Docker Compose walkthrough
• Configuration — database, logging, cog include-list, intents, guild removal, config file/volume locations
• HA architecture — what each of the seven pods does, how they talk to each other, and container runtime details (non-root user, volume permissions, debug builds)
• CLI and application lifecycle
• CogHelperBase reference (for developers)
• Message dispatcher
• Messaging system — the dispatcher/bundle model used by every pod
• Monitoring and observability
• Music deep-dives: overview, media broker, flow
• For setup, tests, and contributing: DEVELOPMENT.md
• For agent-specific guidance: AGENTS.md