SuperRoleManager

A config-driven Discord role manager with state-aware UI and hot-reload configuration built on Pycord. Use modern buttons instead of reactions!

Why?

Most self-role bots start simple but turn into a mess at scale. Discord's built-in role customization is not customizable and requires enabling community features. "Reaction role" bots feel outdated, hacky, and locked around reactions api limitations. Plus, having all categories in one channel sometimes turns into wall of text.

SuperRoleManager takes a different approach. It provides clean and comfortable config to manage all your role categories and options in one place. Then, it renders a dynamic menu where user can choose which specific role category they are interested in, and then pick from there. The buttons are state-aware, so they always show the real role state of the user. The service layer enforces all the rules, so you can have single-select categories without worrying about edge cases. Finally, any config change is hot-reloaded without needing to restart the bot.

Smooth for users and stays maintainable for admins! Win-win!

Key Features

• Role policy lives entirely in config/roles.yaml
• Buttons always show real role state (added/removed live)
• Proper single-select and multi-select handling in one place
• Automatically skips unavailable or missing roles
• Hot-reload: edit the YAML and changes apply immediately

Architecture

main.py                  # Bot startup + persistent views + watcher
cogs/role_menu.py        # Admin command to post the menu
services/role_service.py # All the actual logic and rules
views/                   # Dynamic menus and button handling
models/                  # Typed config structures
utils/                   # Config loading and hot-reload

I kept the UI thin and put the real policy in the service layer. This makes the code predictable and easy to extend.

Example Config Snippet

categories:
  - id: games
    name: Games
    multi_select: false
    embed:
      title: Choose your game
      description: Only one at a time.
      color: 0x5865F2
    roles:
      - id: 1234567890123456789
        name: CS2
        emoji: "🔫"

Supports unicode emojis, custom emoji IDs, role icons, or -1 for none. See roles.yaml for a full example.

Tech Stack

• Python 3.14+
• Pycord with persistent views
• Loguru for logging (I hate the standard logging module)
• PyYAML, python-dotenv

Getting Started

1. Clone the repo
2. Add your BOT_TOKEN to .env
3. Edit config/roles.yaml for your server
4. Run the bot
5. Use role!setup in a channel to publish the menu (the code is in cogs/role_menu.py if you want to customize it)

Feel free to try it or fork it for your server.