ModEx (Mode Executor) is a Discord bot that reorganizes large servers into thematic sections by adjusting roles and channel visibility for each group. It lets you activate complete sets of channels — Whether for movies, music, sweepstakes, events, casual activities, or any other topic that requires automated organization.
Built with:
📋 Table of Contents
ModEx Discord Bot is a structured, multilingual system built to create, edit, manage, and seamlessly switch between fully customized server modes. A mode represents a complete configuration of roles and channels that determines what each member can see or access, allowing large or multi-theme servers to reorganize themselves instantly and efficiently.
The system was originally inspired by the challenge of maintaining different “sections” within a shared community — such as RPG areas, casual spaces, or thematic categories like movies or music. Instead of manually toggling permissions or updating roles for dozens of users, ModEx automates the entire workflow:
- When a mode is activated, all members below the bot's hierarchy receive the corresponding role.
- Only the channels assigned to that mode remain visible to regular members.
- All other channels are hidden automatically.
- Server owners and roles above the bot always retain full visibility.
This approach allows administrators to manage multiple server layouts effortlessly, such as:
- Work/Team Mode: Project channels, task boards, reporting areas, meeting logs, documentation hubs.
- Event Mode: Registration channels, ticket check-in, announcements, schedule boards, voice stages, staff-only areas.
- Study Mode: Subject channels, resource libraries, group rooms, Q&A spaces, notebook uploads.
- Creative Mode: Art dumps, music sharing, writing corners, critique rooms, project showcases.
- Marketplace Mode: Buyer/seller listings, feedback threads, price checks, trade channels.
- Clan/Guild Mode: Raid planning, ranking boards, team coordination, strategy rooms, voice hubs.
- Education/Workshop Mode: Sessions, modules, exercises, instructor-only channels, resource repositories.
- And More!
A mode can also be designated as a reception mode, automatically assigning a specific role to every new member who joins the server, similar to welcome or visitor roles, but without custom greetings. This ensures consistent onboarding and default visibility for newcomers.
Why ModEx?
ModEx provides a powerful, scalable solution for administrators who need:
- 🔁 Admins no longer need to reconfigure permissions every time the server shifts focus.
- 🧩 Community sections can be swapped in or out without rebuilding the server from scratch.
- 🎯 Layouts stay consistent across updates, role changes, and new members joining.
- 🏗️ Large servers with multiple themes or activities can stay organized without fragmenting into separate servers.
| Category | Description | |
|---|---|---|
| 🎯 | Mode System | Create, edit and switch between complete server configurations (roles + channels). Includes reception modes for automatic onboarding. |
| 🛠️ | Smart Automation | Automatic visibility control, conflict detection, role synchronization, and per-mode validation. |
| 📚 | Multilingual Support | Full support for Portuguese and English with per-server language profiles. |
| 🔍 | Logging & Debugging | Centralized logging with detailed debug insights for easier troubleshooting. |
| 🧩 | Modular Design | Separated modules for logic, embeds, language handling, and logging. Easy to extend and maintain. |
| 🛡️ | Permission Safety | Server ownership checks, bot hierarchy validation, and protected modification rules. |
| ⚡ | Optimized Workflow | Cached modes, efficient IO, and responsive reaction-based navigation. |
The project follows a clean and modular architecture, ensuring easy maintenance, scalability, and clear separation of responsibilities.
MODEX_DISCORDBOT/
├── .venv/ # Python virtual environment (IGNORED)
├── .vscode/ # VSCode IDE settings (IGNORED)
├── data/ # Data storage directory
│ ├── config_debug.json # Debug configuration and settings
│ ├── idiomas.json # Language/translation data (PT/EN)
│ └── modos.json # Server modes configuration and storage
├── logs/ # Application log files (IGNORED)
├── src/ # Source code directory
│ ├── __pycache__/ # Python bytecode cache (IGNORED)
│ ├── utils/ # Utility modules
│ │ ├── __pycache__/ # Python bytecode cache (IGNORED)
│ │ ├── drive_sync.py # Google Drive backup and synchronization module
│ │ ├── logger_manager.py # Unified logging system and log management
│ │ └── modos.py # Mode creation, editing, and management logic
│ ├── config.py # Configuration handler and environment variable loader
│ ├── embed.py # Centralized embed builder for all Discord messages
│ ├── idiomas.py # Multilingual text handler (Portuguese/English)
│ └── main.py # Core bot file with commands, events, and startup
├── .env # Environment variables (sensitive data - IGNORED)
├── .gitattributes # Git attributes for line endings and file handling
├── .gitignore # Git ignore patterns for temporary files
├── LICENSE # Project license
├── Procfile # Deployment configuration for Heroku/Railway
├── README.md # Project documentation and setup instructions
├── requirements.txt # Python dependencies list
├── runtime.txt # Python runtime version specification
└── start.sh # Startup script for deployment platformsModEx_DiscordBot/
src (Main)
⦿ src
File Description main.py - Core bot file
- Setup de eventos e comandos
- Inicialização do bot e intents
- Integração das funcionalidades (modos, idiomas, embeds)config.py - Carregamento de variáveis do .env
- Contém caminhos globais (modos, idiomas, data)
- Inicializa constantes usadas pelos módulos
- Cache interno para modosembed.py - Sistema central de geração de embeds
- Templates de erro, confirmação e navegação
- Suporte multilíngue via idiomas.py
- Estilo visual padronizadoidiomas.py - Manipulação de idiomas do servidor
- Leitura dos arquivos de tradução
- Funções para obter texto multilíngue
- Fallback automático para PT-BR.env - Variáveis sensíveis
- TOKEN, PATHS, Google API keys
- Configurações de debug e email
- Não incluso no repositório
utils (Utilities)
⦿ utils
File Description logger_manager.py - Unified logging system
- Console/file handlers
- JSON config loading and saving
- Detailed tracking of bot operations
- Debug mode with extended logsmodos.py - Mode creation and management
- Functions for editing, applying and deleting modes
- Welcome-role and channel validation
- Conflict detection
- JSON persistence and cleanup statesdrive_sync.py - Google Drive backup and synchronization
- Token refresh and authentication handling
- Service Account and user-based auth workflow
- Automatic upload and recovery routines
ModEx offers two distinct setup paths designed for both everyday users and developers who want full control.
If your goal is simply use ModEx immediately on your Discord server, this is the fast lane. No install. No setup. No dependencies. No technical hurdles. Just invite and you're ready to go:
🎉 Add ModEx to Your Discord Server (Instant access, works right away)
If you want to customize, understand the internals, debug, or contribute to the project, you can install ModEx locally and run your own bot instance.
Show full installation steps
git clone https://github.com/Zev-Lonewolf/ModEx_DiscordBot.git
cd ModEx_DiscordBotUsing pip
pip install -U discord.py>=2.0.0 python-dotenvUsing uv (recommended for speed)
uv pip install -U discord.py>=2.0.0 python-dotenvCreate a .env file inside the src/ folder:
TOKEN=your_discord_token_here
PREFIX=!
LANGUAGE_PATH=./languages.json
DEBUG_ENABLED=falseInside the Discord Developer Portal:
-
Enable the bot scope
-
Grant the required permissions:
- Manage Roles
- Manage Channels
- Send Messages
- Manage Messages
- Add Reactions
- Read Messages/View Channels
This section is divided into two paths:
- Using the official bot (recommended for regular users)
- Running a local instance (intended for developers)
Once the bot is invited to your server, all interactions are performed using text commands.
| Command | Aliases | Description | Permission |
|---|---|---|---|
!setup |
Setup, SETUP |
Set server language | manage_guild |
!create |
Create, CREATE |
Create new mode | manage_guild |
!edit |
Edit, EDIT |
Edit existing mode | manage_guild |
!delete |
Delete, DELETE |
Delete a mode | manage_guild |
!switch |
Switch, SWITCH |
Switch to another mode | manage_guild |
!log |
Log, LOG |
Enable/disable debug mode | manage_guild |
!clean |
Clean, CLEAN |
Clear bot messages | manage_guild |
!about |
About, ABOUT |
Information about the bot | none |
!functions |
Functions, FUNCTIONS |
List of functions | none |
Regular users: If you are using the official bot, skip the “Running Locally” section and start here.
- Type
!create - Enter the mode name (validated automatically)
- Select a server role (confirm with ✅)
- Select visible channels (confirm with ✅)
- Configure reception mode if desired (confirm with ✅ or ❌)
- Finalize creation (confirm with ✅)
- ✅ Next: Proceed to the next step
- ❌ Cancel: Abort the current action
- 🔙 Back: Return to the previous step
Note: This section is intended for developers. Regular users do not need to run the bot locally.
Run the bot using:
Using pip:
python src/main.pyUsing uv:
uv run src/main.pyThe project includes automatic validations and error handling. To test:
- Mode creation test:
- Follow the creation flow
!create-
Validation test:
- Try to create a mode with a duplicate name
- Try to reference deleted channels
- Check for role conflict detection
-
Permissions test:
- Try to execute commands without manage_guild permission
- Check denied access logs
-
Multilingual test:
- Select a different language
!Language- Mode System: Create, edit, delete, and switch between modes
- Role Management: Assign roles to modes
- Channel Management: Configure channels by mode
- Reception System: Assign reception positions
- Multilingual: Support for Portuguese and English
- Logs System: Debug mode with tracking
- Web Dashboard: Web interface for remote management
- Automatic Backup: Configuration backup system
- Scheduling: Modes with specific times
- Database Integration: Migration from JSON to dedicated database
- 💬 Open Discussions: Share insights, provide feedback, or ask questions
- 🐛 Report Issues: Submit bugs you find or request new features
- 💡 Send Pull Requests: Review open PRs and send your contributions
Contribution Guidelines
- Fork the Repository: Start by forking the repository to your GitHub account
- Clone Locally: Clone the forked repository using a git client
git clone https://github.com/Zev-Lonewolf/ModEx_DiscordBot- Create a New Branch: Always work on a new branch with a descriptive name
git checkout -b feature/new-feature- Make Your Changes: Develop and test your changes locally
- Commit Your Changes: Commit with a clear message describing the updates
git commit -m ‘Implemented new feature X’- Push to GitHub: Send the changes to the forked repository
git push origin feature/new-feature- Send a Pull Request: Create a PR against the original repository, clearly describing the changes
- Review: After review and approval, your PR will be merged into the main branch. Congratulations on your contribution!
- discord.py — For providing the core library that powers the project
- Discord Developers Community — For guidance, documentation, and shared knowledge
- Contributors — For code improvements, fixes, and enhancements
- All users — For feedback, testing, and helping the project evolve
- Special thanks to all supporting tools and technologies — Editors, platforms, libraries, and ecosystems that made development smoother and more reliable
If this project helped you, inspired you, or saved you a few hours of work, consider giving it a ⭐ on GitHub, it truly makes a difference. You can also follow the people behind the project to stay updated on new releases, improvements, and related work. Every star, follow, and piece of feedback helps keep the project growing. Thanks for the support!
- Gleidson Gonzaga (“Zev”) — Project Owner & Lead Developer
📎 https://github.com/Zev-Lonewolf - Noara Inazawa (“Noa”) — Technical Assistant & Co-Developer
📎 No contact link currently available
This project is licensed under the GNU General Public License v3.0 (GPL-3.0). For full details, see the LICENSE file.
