Moderation & Mutes
Relevant source files
The following files were used as context for generating this wiki page:
The Moderation and Mutes systems provide tools to manage user behavior within a Discord server. These systems allow administrators and moderators to issue punishments, track infractions, and automate the removal of access permissions. The functionality is distributed across specialized cogs that handle standard moderation actions (kick/ban), temporary or permanent mutes, and a point-based warning system.
Sources: redbot/cogs/mod/mod.py, redbot/cogs/mutes/mutes.py, redbot/cogs/warnings/warnings.py
Moderation Cog Architecture
The Mod cog serves as the primary interface for administrative actions. It inherits from multiple mixins to provide a broad feature set, including kick/ban logic, name tracking, and slowmode management.
Key Components
- Kick/Ban Logic: Handles the removal of members from a guild and manages temporary bans.
- Infrastructure Tracking: Records past nicknames and usernames to help identify users across identity changes.
- Automated Protections: Includes mention spam protection and duplicate message deletion.
Sources: redbot/cogs/mod/mod.py:34-52, redbot/cogs/mod/settings.py:171-331
Moderation Configuration Options
| Option | Type | Description |
|---|---|---|
mention_spam | dict | Sets thresholds for warn, kick, or ban actions when a user pings too many people. |
delete_repeats | int | Automatically deletes messages after a set number of repetitions. |
respect_hierarchy | bool | Prevents moderators from taking action against users with higher roles. |
dm_on_kickban | bool | Sends a direct message to the user explaining the reason for the action. |
default_days | int | Number of days of message history to delete upon banning (0-7). |
Sources: redbot/cogs/mod/mod.py:54-71, redbot/cogs/mod/settings.py:15-130
Mutes System
The Mutes cog manages the restriction of user communication. It supports three distinct methods: role-based mutes, channel-specific overwrites, and native Discord timeouts.
Mute Logic Flow
The system first checks if a dedicated "Muted" role exists. If configured, the bot applies this role to the user. If no role is set, the system falls back to using Discord's built-in Timeout feature (for durations up to 28 days).
The system uses an background loop to handle automatic unmuting. This loop executes every 30 seconds to check for expired mutes in the configuration.
Sources: redbot/cogs/mutes/mutes.py:149-166, redbot/cogs/mutes/mutes.py:808-854
Channel-Specific Mutes
Moderators can mute users in specific text or voice channels. The bot creates local permission overwrites for the user, setting send_messages or speak to False. These overwrites are cached in the bot's configuration to allow for restoration if the user is unmuted.
Sources: redbot/cogs/mutes/mutes.py:906-993
Point-Based Warning System
The Warnings cog allows moderators to assign points to users for specific infractions. This system can trigger automated actions based on cumulative point thresholds.
Warning Components
- Reasons: Pre-configured templates containing a description and a point value.
- Actions: Automated commands (macros) that execute when a user exceeds a specific point threshold.
- Member Data: Stores the total points, current status, and a history of individual warnings for each member.
Sources: redbot/cogs/warnings/warnings.py:27-40, redbot/cogs/warnings/warnings.py:173-195
Warning Process Flow
Automation and Immunity
The core system provides an "Autoimmune" feature to protect specific users or roles from automated moderation actions, such as duplicate message deletion or mention spam filters.
Managing Immunity
Administrators use the autoimmune command group to manage the list of protected IDs. The bot checks these IDs before performing any automated cleanup or punishment.
# Check if a user is immune
if await ctx.bot.is_automod_immune(user_or_role):
await ctx.send(_("They are immune."))
Sources: redbot/core/core_commands.py:1552-1616
Modlog Integration
The modlogset commands configure where and how moderation actions are recorded. Every punishment (mute, kick, ban, warning) can generate a "case" in a designated modlog channel.
- Case Creation: Includes the moderator, the target user, the reason, and the duration (if applicable).
- Casetypes: Actions like
warning,unwarned,smute, andsunmuteare registered as distinct types with unique emojis and labels.
Sources: redbot/core/core_commands.py:1085-1155, redbot/cogs/warnings/warnings.py:73-94
Modlog Case Types Summary
| Action Type | Cog | Modlog ID | Description |
|---|---|---|---|
| Warning | Warnings | warning | Point-based infraction recorded. |
| Server Mute | Mutes | smute | Mute role applied or Timeout set. |
| Channel Mute | Mutes | cmute | Overwrites applied to a specific channel. |
| Ban | Mod | ban | User removed from guild permanently. |
| Hackban | Warnings | hackban | Ban issued for a user not currently in the server. |
Sources: redbot/cogs/mutes/mutes.py:716-726, redbot/cogs/warnings/warnings.py:461-477, redbot/cogs/warnings/warnings.py:382-395
Summary
The Moderation and Mutes systems work together to provide a tiered disciplinary structure. The Mod cog handles high-level guild security, Mutes provides granular communication control, and Warnings enables progressive punishment through automation. Centralized configuration in Core ensures that automated systems respect role hierarchies and immunity settings.
Sources: redbot/cogs/mod/mod.py, redbot/cogs/mutes/mutes.py, redbot/cogs/warnings/warnings.py, redbot/core/core_commands.py