🧩 Cogs¶

This page documents the main live Magikal bot cogs.

The current source of truth for loaded cogs is:

/home/magikalbot/magikal-bot/bot/main.py

Cogs live in:

/home/magikalbot/magikal-bot/bot/cogs/

Keep this page synced

When a cog is added, removed, renamed, or disabled, update this page.

The live load list in bot/main.py is the source of truth.

What is a cog?¶

A cog is a Discord.py module that groups related bot commands, listeners, buttons, tasks, and feature logic.

Most feature code should live in cogs.

Shared helper code should live in:

bot/utils/

Storage access should go through:

bot/storage/

Database models and low-level database manager logic live in:

bot/database.py

Current loaded cogs¶

Cog	File	Main purpose
Moderation	`bot/cogs/moderation.py`	Warnings, timeout, quarantine, kick, ban, purge, slowmode, lock/unlock
Autoroles	`bot/cogs/autoroles.py`	Automatic role assignment
Reaction Roles	`bot/cogs/reaction_roles.py`	Reaction role panels and role assignment
Temp VC v2	`bot/cogs/tempvc_v2.py`	Temporary voice channels, ownership, AFK handling, panel controls
Basic	`bot/cogs/basic.py`	Core commands, help, info, sync, healthcheck, reload
Admin Config	`bot/cogs/admin_config.py`	Server configuration commands
Storage Diagnostics	`bot/cogs/diag_storage.py`	Storage and Redis/Postgres diagnostics
Tickets	`bot/cogs/tickets.py`	Tickets, recruitment applications, Q&A, approve/decline/finalise
Ship Info UEX	`bot/cogs/shipinfo_uex.py`	Star Citizen ship lookup
Market UEX	`bot/cogs/market_uex.py`	UEX market, items, commodities, refinery, weapons
Embed Tools	`bot/cogs/embed_tools.py`	Embed building and editing tools
RSI Profile	`bot/cogs/rsi_profile.py`	RSI handle/profile lookup
Welcome	`bot/cogs/welcome.py`	Welcome, rules, visitor/introduction flow
Command Diagnostics	`bot/cogs/diag_commands.py`	Command registry diagnostics
Help Auditor	`bot/cogs/help_auditor.py`	Help registry audit/export
Help Panel	`bot/cogs/help_panel.py`	Role-aware help panels and staff handbook
Event Modal	`bot/cogs/event_modal.py`	Discord event creation modal flow
Automod	`bot/cogs/automod.py`	Automated moderation checks and actions
Modlog Events	`bot/cogs/modlog_events.py`	Message/member/server event logging
Voice Events	`bot/cogs/voice_events.py`	Voice channel join/leave/move logging
Banking	`bot/cogs/banking.py`	Org treasury, ledger, and loan tools
Recruit Config	`bot/cogs/recruit_config.py`	Recruitment configuration and member removal tracking
Events	`bot/cogs/events.py`	Event signups, roles, rosters, and event records
XP	`bot/cogs/xp.py`	XP, levels, rank roles, leaderboards, voice XP
Command Dump	`bot/cogs/command_dump.py`	Owner command export/debug helper
Roles Config	`bot/cogs/roles_config.py`	Role/capability configuration
RSI Status	`bot/cogs/rsi_status.py`	RSI/Star Citizen status tools
AI Assistant	`bot/cogs/ai_assistant.py`	AI assistant slash commands and AI channel replies

Cog details¶

Moderation¶

File:

bot/cogs/moderation.py

Main areas:

warnings
clear warns
timeout and untimeout
quarantine and unquarantine
kick, ban, unban, softban
purge commands
slowmode
lock and unlock
moderation action persistence
modlog integration

Storage/config:

uses config_storage
uses make_pid
persists warning/moderation actions

Moderation safety

Moderation changes can affect real server members.

Test carefully and check logs after changes.

Autoroles¶

File:

bot/cogs/autoroles.py

Main areas:

automatic role assignment
autorole config
join handling

Storage/config:

uses config_storage
uses privacy-safe PID logging

Reaction Roles¶

File:

bot/cogs/reaction_roles.py`

Main areas:

reaction role setup
role assignment/removal from reactions
panel/display updates
role select flows

Storage/config:

uses config_storage
stores reaction role mappings

Temp VC v2¶

File:

bot/cogs/tempvc_v2.py

Main areas:

temporary voice channel creation
lobby/creator channels
owner detection
owner transfer
AFK handling
persistent panel controls
voice modlog integration

Storage/config:

uses config_storage
uses state_storage
uses PIDs for owner tracking

Temp VC state

Temp VC touches live Discord voice channels and runtime state.

Be careful with owner transfer, cleanup, AFK logic, and restart recovery.

Basic¶

File:

bot/cogs/basic.py

Main areas:

ping
info
help
command list
slash command sync
healthcheck
reload cog

Risk notes:

contains owner/admin operational commands
slash sync changes should be checked carefully

Admin Config¶

File:

bot/cogs/admin_config.py

Main areas:

server prefix/config commands
automod config
moderation config
forget/prune warn tools
config export/validation

Storage/config:

uses config_storage
uses PIDs for privacy-sensitive actions

Storage Diagnostics¶

File:

bot/cogs/diag_storage.py

Main areas:

storage diagnostics
Redis smoke testing
owner-only checks

Risk notes:

diagnostics should not expose secrets or raw IDs

Tickets¶

File:

bot/cogs/tickets.py

Main areas:

ticket panels
support tickets
recruitment applications
recruitment Q&A
approve/decline/finalise flow
record embeds
DM-on-close behaviour
RSI nickname sync settings

Storage/config:

uses config_storage
uses recruitment application persistence
uses PIDs for applicant/staff records

Ticket flow safety

Ticket changes can affect recruitment records and permanent application history.

Check record embeds, Q&A persistence, and finalise behaviour after edits.

Ship Info UEX¶

File:

bot/cogs/shipinfo_uex.py

Main areas:

/ship lookup
ship image/cache handling
UEX data
ship command role gates

Storage/config:

uses file cache
uses config role gates

Market UEX¶

File:

bot/cogs/market_uex.py

Main areas:

/item
/weapon
market listings
commodities
refinery data
UUID/item registry
UEX/wiki integration
command gating

Storage/config:

uses file caches
uses command role gates through config_storage

Risk notes:

large cog
external API/cache behaviour should be checked carefully
first-load image behaviour has been a known pain point

Embed Tools¶

File:

bot/cogs/embed_tools.py

Main areas:

embed creation
embed editing
embed posting tools

Risk notes:

check permissions carefully because this can post public server content

RSI Profile¶

File:

bot/cogs/rsi_profile.py

Main areas:

RSI handle lookup
RSI profile display
Star Citizen API/fallback integration

Storage/config:

uses SC API helper

Welcome¶

File:

bot/cogs/welcome.py

Main areas:

welcome messages
rules flow
visitor role handling
introduction channel/message flow

Storage/config:

uses config_storage
uses PIDs in join/introduction logs

Command Diagnostics¶

File:

bot/cogs/diag_commands.py

Main areas:

command registry diagnostics
command export/debugging

Risk notes:

should stay admin/owner restricted

Help Auditor¶

File:

bot/cogs/help_auditor.py

Main areas:

help registry auditing
autosave/export of command metadata
command visibility checks

Risk notes:

useful for keeping help docs honest

Help Panel¶

File:

bot/cogs/help_panel.py

Main areas:

role-aware help panels
staff handbook
public/admin/mod/helper/events/finance help views

Storage/config:

depends on command/audience/capability rules

File:

bot/cogs/event_modal.py

Main areas:

Discord event creation
cover image changes
event listing
event cancellation

Risk notes:

works with Discord scheduled events
permissions and Discord API errors should be handled cleanly

Automod¶

File:

bot/cogs/automod.py

Main areas:

automated checks
domain rules
channel/role exemptions
moderation actions
alerts/events

Storage/config:

uses config_storage
uses PIDs

Automod safety

Automod can affect real user messages and moderation actions.

Test changes carefully and keep logging privacy-safe.

Modlog Events¶

File:

bot/cogs/modlog_events.py

Main areas:

message delete/edit logging
member/server event logging
member presence routing
modlog exclusions

Storage/config:

uses modlog settings
uses PIDs

Voice Events¶

File:

bot/cogs/voice_events.py

Main areas:

voice join/leave/move logs
voice bucket routing
voice exclusions

Storage/config:

uses config_storage

Banking¶

File:

bot/cogs/banking.py

Main areas:

treasury
ledger
loans
repayments
finance tools

Storage/config:

currently uses bot.database_manager directly

Database exception

banking.py currently uses direct database manager/session access.

Treat this as an existing exception. Do not copy this pattern into new cogs without review.

Recruit Config¶

File:

bot/cogs/recruit_config.py

Main areas:

recruitment access mode
Q&A config
removal/member status updates
application status management

Storage/config:

uses recruitment application persistence
uses PIDs

Events¶

File:

bot/cogs/events.py

Main areas:

event records
event roles
signups
rosters
event message linking

Storage/config:

uses config_storage
persists event data

XP¶

File:

bot/cogs/xp.py

Main areas:

message XP
voice XP
leaderboards
rank roles
XP cards
exclusions
PID migration helpers

Storage/config:

uses config_storage
uses PIDs heavily

Command Dump¶

File:

bot/cogs/command_dump.py

Main areas:

owner-only command dump/export

Risk notes:

useful for docs/help generation
should remain restricted

Roles Config¶

File:

bot/cogs/roles_config.py

Main areas:

role/capability mapping
command access roles
staff capability config

Storage/config:

uses config_storage

RSI Status¶

File:

bot/cogs/rsi_status.py

Main areas:

RSI / Star Citizen status updates
target channel setup

Risk notes:

external status/API behaviour should fail gracefully

AI Assistant¶

File:

bot/cogs/ai_assistant.py

Main areas:

AI slash commands
AI channel replies
Star Citizen helper answers
ship info integration

Risk notes:

must avoid outdated Star Citizen claims where possible
should keep answers readable and avoid noisy formatting

Adding or changing a cog¶

See:

Developer Guide -> Adding a Cog

Basic rule:

edit the live file
keep change focused
use config_storage
use privacy-safe logging
restart bot
check logs
update docs if behaviour changed

Red flags¶

Stop and review if a cog change:

adds persistent data
needs Alembic
touches tickets/recruitment
touches moderation
touches Temp VC state
touches banking/XP/event persistence
changes command permissions
changes modlog routing
introduces direct DB sessions
logs raw IDs or secrets
adds a background task
adds a persistent view

Rule¶

Cogs should stay focused, privacy-safe, Postgres-backed where persistent, and documented from the live files.

🧩 Cogs¶

What is a cog?¶

Current loaded cogs¶

Cog details¶

Moderation¶

Autoroles¶

Reaction Roles¶

Temp VC v2¶

Basic¶

Admin Config¶

Storage Diagnostics¶

Tickets¶

Ship Info UEX¶

Market UEX¶

Embed Tools¶

RSI Profile¶

Welcome¶

Command Diagnostics¶

Help Auditor¶

Help Panel¶

Event Modal¶

Automod¶

Modlog Events¶

Voice Events¶

Banking¶

Recruit Config¶

Events¶

XP¶

Command Dump¶

Roles Config¶

RSI Status¶

AI Assistant¶

Adding or changing a cog¶

Red flags¶

Rule¶