EmperorFred

Multi-platform moderation bot for Twitch and Discord. This repository contains two separate bots (Twitch and Discord) that can be run concurrently in a single Python process using asyncio.

The project uses:

• Python 3.13+
• discord.py (Discord bot)
• TwitchIO v3 with EventSub over WebSocket (Twitch bot)
• SQLAlchemy (database)
• python-dotenv (env config)
• requests
• uv as the package manager (pyproject.toml + uv.lock)

Overview

Entry point: bot.py

bot.py loads environment variables (via python-dotenv), then starts both bots concurrently:

• Discord bot class: discord_bot.bot.EmperorFredDiscordBot
• Twitch bot class: twitch_bot.bot.TwitchBot

Both bots expose simple commands and support a controlled in-process restart via a shared RestartController.

Requirements

• Python 3.13 or newer
• uv (recommended) or pip

Project dependencies are declared in pyproject.toml. A lockfile uv.lock is present.

Setup

1. Clone the repository

git clone <your-fork-or-origin>
cd EmperorFred

2. Create a virtual environment and install dependencies

• Using uv (recommended):

uv venv
source .venv/bin/activate
uv pip install -r <(uv pip compile pyproject.toml)

• Or using pip:

python -m venv .venv
source .venv/bin/activate
pip install -r <(pip-compile pyproject.toml)  # if you use pip-tools
# or simply
pip install -e .

Note: If you don't use pip-tools, you can install directly from the project metadata:

pip install .

3. Configure environment variables

Create a .env file in the project root (or export variables in your shell). See the full list in the next section.

Configuration (Environment Variables)

Environment variables are read in discord_bot/config.py and twitch_bot/config.py, and shared DB settings in both.

Required/optional variables:

Discord

• DISCORD_TOKEN — Discord bot token (required to run Discord bot)
• DISCORD_COMMAND_PREFIX — e.g. ! (optional; defaults handled by code to ! if unset)
• DISCORD_GUILD_ID — guild/server ID used by the app in some contexts (optional)

Twitch

• TWITCH_CLIENT_ID — Twitch application client ID (required for Twitch operations)
• TWITCH_CLIENT_SECRET — Twitch application client secret (required)
• TWITCH_TOKEN — OAuth token for Twitch bot account; if missing the Twitch bot will not start
• TWITCH_CHANNEL — channel name (used for logs/hints)
• TWITCH_BOT_ID — numeric user ID for the bot account (required to subscribe to chat messages)
• TWITCH_OWNER_ID — numeric broadcaster (channel) user ID (required to subscribe)
• TWITCH_COMMAND_PREFIX — e.g. ! (optional)
• TWITCH_REDIRECT_URL — redirect URI used during OAuth flows (optional)

Database

• DB_CONN_STR — SQLAlchemy connection string (required). Example for SQLite file DB:
  • sqlite:///data/bot.db

Notes

• The project uses python-dotenv, so variables defined in .env are loaded automatically by bot.py.
• TwitchIO v3 relies on EventSub for chat subscriptions. Ensure TWITCH_OWNER_ID and TWITCH_BOT_ID are set.
• A tokens file may be referenced by the Twitch bot startup path (see bot.py, currently opens .tio.tokens.json).

TODOs

• Document the full OAuth/token provisioning flow for Twitch, including generating and storing tokens in .tio.tokens.json (or the expected file name) and required scopes.

Running

Run both bots together (recommended during development):

python bot.py

Behavior:

• If DISCORD_TOKEN is set, the Discord bot starts.
• If TWITCH_TOKEN is NOT set, the Twitch bot will log a warning and skip starting.
• On successful Twitch start, the bot subscribes to EventSub ChatMessage for the configured broadcaster/user IDs.

Select which bot to run (CLI):

• Both (default):

  python bot.py
  

• Discord only:

  python bot.py --bot discord
  

• Twitch only:

  python bot.py --bot twitch
  

• Short flag works too (values: discord, twitch, both):

  python bot.py -b both
  

Commands

Discord (discord_bot/cogs):

• !ping — replies with a health check message.
• !restart — owner-only; gracefully restarts the Discord bot instance.

Twitch (twitch_bot/commands):

• !ping — replies with a health check message including the chatter name.
• !restart — moderator-only; gracefully restarts the Twitch bot instance.

Project Structure

.
├─ bot.py                         # Entry point; runs both bots concurrently
├─ pyproject.toml                 # Project metadata and dependencies
├─ uv.lock                        # Lockfile for uv (package manager)
├─ data/
│  ├─ bot.db                      # Example SQLite database (if used)
│  └─ models/
│     ├─ DiscordCog.py            # Tracks Discord cog activation flags
│     ├─ TwitchComponent.py       # Tracks Twitch command components and active flags
│     └─ TwitchLiveNotification.py
├─ libs/
│  ├─ Db.py                       # SQLAlchemy setup, model base, auto-create tables
│  ├─ Cog.py                      # Base for Discord cogs
│  ├─ RestartController.py        # Simple restart signaling between loops
│  ├─ Channels.py, Guilds.py, Twitch.py, __init__.py
├─ discord_bot/
│  ├─ bot.py                      # Discord bot class (loads cogs dynamically)
│  ├─ config.py, config.json      # Config loader + example JSON (not auto-loaded)
│  ├─ cogs/
│  │  ├─ ping.py                  # !ping command
│  │  └─ restart.py               # !restart (owner-only)
│  └─ embeds/
│     └─ TwitchGameNotificationEmbed.py
└─ twitch_bot/
   ├─ bot.py                      # Twitch bot class (EventSub subscription; dynamic components)
   ├─ config.py                   # Twitch env config
   └─ commands/
      ├─ ping.py                  # !ping command
      └─ restart.py               # !restart (moderator-only)
├─ tests/                         # Pytest-based unit tests (offline)
│  ├─ conftest.py                 # Fixtures and env setup
│  ├─ test_db_and_models.py
│  ├─ test_discord_bot_load_cogs.py
│  ├─ test_twitch_bot_load_commands.py
│  └─ test_restart_controller.py

Database

The project uses SQLAlchemy. libs/Db.py:

• Creates an engine from DB_CONN_STR
• Defines a Db.Model declarative base for models under data/models
• Imports all models from data/models and creates tables on startup

Models

• data/models/TwitchComponent.py maintains component activation flags for Twitch command modules. When twitch_bot.bot.TwitchBot.load_commands() scans twitch_bot/commands, it checks the DB record to decide whether to load a component.
• data/models/DiscordCog.py maintains activation flags for Discord cogs. When discord_bot.bot.EmperorFredDiscordBot.load_cogs() scans discord_bot/cogs, it checks the DB record to decide whether to load a cog.
• data/models/TwitchLiveNotification.py stores usernames for Discord-side Twitch live notifications (used by the TwitchNotificationsCog).

Scripts

There are no custom CLI scripts or tool entries defined in pyproject.toml. Use python bot.py to run the application. Managing dependencies is done via uv/pip as described above.

Testing

The project uses pytest.

How to run tests:

pip install pytest
pytest -q

Notes

• Tests are offline and avoid network calls. They focus on:
  • libs/RestartController behavior
  • Database/model initialization and defaults
  • Discord cogs loading (registering ping and restart)
  • Twitch components loading and honoring DB activation flags
• A temporary SQLite database is used per test via DB_CONN_STR provided by a pytest fixture.

TODOs

• Add integration tests (e.g., with mocked Discord/Twitch clients or local simulators).

Development Notes

• Code style follows the surrounding modules; there is no configured formatter/linter in pyproject.toml.
• Consider adding Ruff/Black/mypy configuration and pre-commit hooks. (TODO)

License

No license file is included in this repository.

TODO

• Choose and add a LICENSE (e.g., MIT, Apache-2.0) and update this section.