Discord bot in Python (discord.py 2)

# AGENTS.md: Discord bot (Python, discord.py 2)

## Layout
```
bot.py            creates the Bot, loads cogs in setup_hook, reads the token from the environment
cogs/<name>.py    one feature per cog: app commands plus an async setup(bot) function
tests/            pytest for command logic and the command payloads, no network
```
Run with `uv run python bot.py`. Tests: `uv run pytest`. Lint: `uv run ruff check` and `uv run ruff format --check`.

## Commands
- Slash commands (`app_commands`), not prefix commands that need the privileged message content intent.
- Every command and option has a description (`description=` and `@app_commands.describe`). Names are lowercase,
  1-32 characters.
- Constrain options in the schema: `app_commands.Range[int, 1, 20]`, `Range[str, 1, 200]`, `Choice` lists. Discord
  enforces these before your code runs.
- Keep logic in plain functions that take plain values, so tests do not need Discord objects. New commands: use the
  `discord-py-command` skill.

## Interactions
- Respond within 3 seconds. For slow work call `await interaction.response.defer()` first, then
  `await interaction.followup.send(...)`.
- Private replies: `ephemeral=True`. Errors go to a command `.error` handler (or `tree.on_error`): log the exception,
  reply with a short ephemeral message, never a traceback.
- Moderation commands set `@app_commands.default_permissions(...)` and re-check permissions in code.
- Cooldowns on costly commands: `@app_commands.checks.cooldown(rate, per, key=...)`.

## Syncing
- Do not call `tree.sync()` on every start; it is rate limited. Sync by hand, to a dev guild while developing
  (instant), and globally only for a release.
- After changing a command's name, options or descriptions, remind the user to sync.

## Token and intents
- `DISCORD_TOKEN` comes from the environment or a git-ignored `.env`. Never print, log or commit it. If it leaks, the
  user must reset it in the Developer Portal.
- `discord.Intents.default()` is enough for slash commands. `members`, `presences` and `message_content` are
  privileged; ask before enabling them.

## Dependencies
- `uv add "discord.py==2.7.1"` and commit `uv.lock`. Ask before adding anything else. Never pass user input to a
  shell, `eval` or a SQL string.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `discord-py-command`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Discord bot in Python (discord.py 2)" v1.0.0 — https://loadout.jnw-it.com/loadouts/discord-bot-python/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `discord-py-command`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Discord bot in Python (discord.py 2)" v1.0.0 — https://loadout.jnw-it.com/loadouts/discord-bot-python/ -->

---
name: discord-py-command
description: Add a slash command to a discord.py 2 bot as a cog, with described and range-limited options, a cooldown, an error handler and offline tests of the logic and the command payload.
---

# Add a discord.py slash command

Examples: `references/dice.py` (cog), `references/bot.py` (entry point) and `references/test_dice.py` (tests).

1. Put the logic in a plain function that takes plain values and returns plain values (`roll(count, sides, rng)`).
   Inject randomness, clocks and HTTP clients so tests can control them.
2. Create or extend a cog in `cogs/<feature>.py`:
   - `@app_commands.command(name=..., description=...)`
   - `@app_commands.describe(...)` for every option
   - `app_commands.Range[...]` or `Choice` for limits
   - a cooldown for anything costly, and `@app_commands.default_permissions` for moderation
3. Respond within 3 seconds; defer first if the work may be slow.
4. Add a `.error` handler: cooldowns get a friendly ephemeral message; anything else is logged and gets
   "Something went wrong."
5. Export `async def setup(bot)` and add the module to the extensions list in `bot.py`.
6. Tests, with no network: the logic function (including bad input), and the payload Discord will receive:
   `bot.add_cog(...)`, then `c.to_dict(bot.tree)` for each command, checking names, descriptions and limits.
7. Run `uv run pytest`, `uv run ruff check` and `uv run ruff format --check`. Remind the user to sync commands.

"""Dice cog: one slash command with validated options, a cooldown and logic that can be tested offline."""

import logging
import random

import discord
from discord import app_commands
from discord.ext import commands

log = logging.getLogger(__name__)

MAX_DICE = 20


def roll(count: int, sides: int, rng: random.Random) -> list[int]:
    """Pure logic, no Discord objects: easy to test."""
    if not 1 <= count <= MAX_DICE:
        raise ValueError(f"count must be 1-{MAX_DICE}")
    if not 2 <= sides <= 1000:
        raise ValueError("sides must be 2-1000")
    return [rng.randint(1, sides) for _ in range(count)]


def format_roll(results: list[int], sides: int) -> str:
    total = sum(results)
    shown = ", ".join(map(str, results)) if len(results) <= 10 else f"{len(results)} dice"
    return f"Rolled {len(results)}d{sides}: {shown} (total {total})"


class Dice(commands.Cog):
    def __init__(self, bot: commands.Bot, rng: random.Random | None = None) -> None:
        self.bot = bot
        self.rng = rng or random.Random()

    @app_commands.command(name="roll", description="Roll dice, for example 3 six-sided dice")
    @app_commands.describe(count="How many dice (1-20)", sides="Sides per die (2-1000)")
    @app_commands.checks.cooldown(1, 3.0, key=lambda i: i.user.id)
    async def roll_command(
        self,
        interaction: discord.Interaction,
        count: app_commands.Range[int, 1, MAX_DICE] = 1,
        sides: app_commands.Range[int, 2, 1000] = 6,
    ) -> None:
        results = roll(count, sides, self.rng)
        await interaction.response.send_message(format_roll(results, sides))

    @roll_command.error
    async def roll_error(self, interaction: discord.Interaction, error: app_commands.AppCommandError) -> None:
        if isinstance(error, app_commands.CommandOnCooldown):
            message = f"Slow down: try again in {error.retry_after:.0f}s."
        else:
            log.exception("roll failed", exc_info=error)
            message = "Something went wrong."
        if interaction.response.is_done():
            await interaction.followup.send(message, ephemeral=True)
        else:
            await interaction.response.send_message(message, ephemeral=True)


async def setup(bot: commands.Bot) -> None:
    await bot.add_cog(Dice(bot))

"""Entry point: minimal intents, cogs loaded in setup_hook, token from the environment, no sync on start."""

import asyncio
import logging
import os

import discord
from discord.ext import commands

EXTENSIONS = ["cogs.dice"]


class Bot(commands.Bot):
    def __init__(self) -> None:
        # Slash commands need no privileged intents. Do not enable message_content or members unless required.
        super().__init__(command_prefix=commands.when_mentioned, intents=discord.Intents.default())

    async def setup_hook(self) -> None:
        for ext in EXTENSIONS:
            await self.load_extension(ext)
        guild_id = os.environ.get("DISCORD_DEV_GUILD_ID")
        if os.environ.get("SYNC_COMMANDS") == "1" and guild_id:
            # Sync by hand, to one dev guild: instant, and avoids the global sync rate limit.
            guild = discord.Object(id=int(guild_id))
            self.tree.copy_global_to(guild=guild)
            synced = await self.tree.sync(guild=guild)
            logging.info("synced %d commands to guild %s", len(synced), guild_id)


async def main() -> None:
    token = os.environ.get("DISCORD_TOKEN")
    if not token:
        raise SystemExit("DISCORD_TOKEN is not set (put it in .env, never in code)")
    discord.utils.setup_logging()
    async with Bot() as bot:
        await bot.start(token)


if __name__ == "__main__":
    asyncio.run(main())

import asyncio
import random

import discord
import pytest
from discord.ext import commands

from cogs.dice import Dice, format_roll, roll


def test_roll_is_deterministic_with_a_seeded_rng():
    assert roll(3, 6, random.Random(42)) == roll(3, 6, random.Random(42))
    assert all(1 <= r <= 6 for r in roll(20, 6, random.Random(1)))


@pytest.mark.parametrize(("count", "sides"), [(0, 6), (21, 6), (1, 1), (1, 1001)])
def test_roll_rejects_out_of_range(count, sides):
    with pytest.raises(ValueError):
        roll(count, sides, random.Random(0))


def test_format_roll_summarises_many_dice():
    assert format_roll([1, 2, 3], 6) == "Rolled 3d6: 1, 2, 3 (total 6)"
    assert format_roll([1] * 12, 4) == "Rolled 12d4: 12 dice (total 12)"


def test_command_payload_registers_offline():
    async def build():
        bot = commands.Bot(command_prefix=commands.when_mentioned, intents=discord.Intents.default())
        await bot.add_cog(Dice(bot))
        return [c.to_dict(bot.tree) for c in bot.tree.get_commands()]

    (payload,) = asyncio.run(build())
    assert payload["name"] == "roll"
    options = {o["name"]: o for o in payload["options"]}
    assert options["count"]["description"] == "How many dice (1-20)"
    assert (options["count"]["min_value"], options["count"]["max_value"]) == (1, 20)
    assert options["sides"]["max_value"] == 1000
    assert not options["count"]["required"]