31 slash commands + 2 context menus, all verified to load. Common info commands (ping, help, serverinfo, userinfo, rank, leaderboard) are hybrid — they work as both /cmd and !cmd.

Quick start

# 1. Create & activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure secrets
cp .env.example .env               # then edit .env (see Part 1 below)

# 4. Run
python bot.py

Python 3.14 note: discord.py needs the audioop module for voice, which was removed from the standard library in Python 3.13. The audioop-lts package restores it and is pulled in automatically as a dependency — no action needed.

Music note: the music cog streams audio through FFmpeg, which must be installed and on your PATH (sudo apt install ffmpeg, brew install ffmpeg, …). The Docker image installs it for you. PyNaCl and yt-dlp come from requirements.txt.

Part 1 — Discord Developer Portal setup

Everything below happens at https://discord.com/developers/applications.

1.1 Create the application

1. Click New Application, name it Codex, accept the terms, Create.
2. On General Information, set the description, app icon, and tags. Copy the Application ID → this is APPLICATION_ID in your .env.
3. (Optional) Set Interactions Endpoint URL only if you ever go HTTP-only. With discord.py you connect over the gateway, so leave this blank.

1.2 The Bot user & token

1. Open the Bot tab.
2. Click Reset Token, confirm, and copy it → this is DISCORD_TOKEN in .env. Treat it like a password; never commit it. (.env is already git-ignored.)
3. Set the bot's username, avatar, and banner here.
4. Public Bot — turn OFF while it's a private friends' bot; ON when you want anyone to be able to invite it.
5. Requires OAuth2 Code Grant — leave OFF unless you have a backend doing the auth-code flow.

1.3 Privileged Gateway Intents ← easy to miss

Still on the Bot tab, scroll to Privileged Gateway Intents and enable all three:

• Presence Intent — member online status / activities.
• Server Members Intent — join/leave events, member lists, role automation.
• Message Content Intent — read message text (needed for the leveling system, prefix commands, and AI replies).

These mirror the three privileged intents Codex requests in config.py. If they're off here, the bot crashes on login with PrivilegedIntentsRequired.

Once your bot is in 100+ servers you must apply for verification to keep privileged intents. For a private friends' server you're fine.

1.4 Installation contexts (Guild install vs User install)

Open the Installation tab. Discord now supports two install targets:

• Guild Install — the classic "add bot to a server." Set Scopes to bot + applications.commands and pick default permissions.
• User Install — installs the app to a user, so its commands work in DMs and in servers where the bot isn't a member. Great for personal utility commands.

Pick the Install Link type (Discord Provided Link is easiest), and the generated URL is what you share to add Codex.

1.5 OAuth2 — scopes & permissions (manual invite URL)

If you'd rather build the invite link by hand, open OAuth2 → URL Generator:

1. Scopes: check bot and applications.commands.
2. A Bot Permissions box appears. For Codex's current + planned features, select: View Channels, Send Messages, Send Messages in Threads, Embed Links, Attach Files, Read Message History, Add Reactions, Use External Emojis, Manage Messages (for /clear), Manage Roles (reaction roles / level roles), Kick Members, Ban Members, Moderate Members (timeouts), Manage Events, Connect + Speak (voice/music later).
3. Copy the generated URL at the bottom, open it, pick your server, Authorize.

Prefer not to grant Administrator — it's a security risk and hides which permissions a feature actually needs.

1.6 Command syncing (and instant updates while testing)

Codex syncs its slash commands globally on startup, so every server it's in gets them. Global syncs can take up to ~1 hour to appear the first time.

While developing, that wait is annoying, so there's an owner-only prefix command:

• !sync guild — sync to the current server instantly (great for testing).
• !sync — force a global re-sync (e.g. after adding a command).
• !sync clear — remove the current server's guild-specific commands (clears duplicates if you previously used a per-guild sync).

You can also mention the bot: @Codex sync. (DEV_GUILD_ID in .env is legacy and no longer used — global sync is automatic.)

Part 2 — Run it

1. Fill in .env:

   DISCORD_TOKEN=your-bot-token
   APPLICATION_ID=your-app-id
   DEV_GUILD_ID=your-test-server-id   # optional but recommended while developing
   

2. python bot.py
3. You should see Synced N commands… and Online as Codex#1234. Type / in your server and Codex's commands appear.

Part 3 — Mapping every Discord feature to Codex

You asked to use as much of what Discord offers as possible. Here's the full surface and where each piece lives (✅ built, 🔜 on the roadmap):

Enabling Premium (App Subscriptions)

The premium cog gates perks on a Discord subscription SKU — Discord handles the payment, so there's no billing code on our side. To turn it on:

1. Developer Portal → Monetization — complete the eligibility steps and create a subscription SKU. (Monetization has requirements; the cog runs fine unconfigured until you're approved.)
2. Run /premium skus (owner-only; the app owner is detected automatically — OWNER_IDS in .env is only for adding extra owners) to read the SKU's ID.
3. Put it in PREMIUM_SKU_ID (.env) and restart. /premium status and the native upgrade button now reflect real subscriptions.

Gate any command elsewhere with the same one-line entitlement check the cog uses.

Project structure

codex-bot/
├── bot.py              # entry point: CodexBot, extension loading, command sync
├── config.py           # env loading, intents, brand colour
├── requirements.txt
├── .env.example        # copy to .env
├── core/
│   └── database.py     # async SQLite helper + schema
└── cogs/               # one module per feature area
    ├── general.py
    ├── events.py
    ├── moderation.py
    ├── components.py
    ├── social.py
    ├── ai.py           # Claude /ask, /chat (cached), /summarize
    ├── study.py        # pomodoro, reminders, flashcards
    ├── roles.py        # self-assign + level roles
    ├── gaming.py       # polls, dice, trivia, LFG
    ├── automod.py      # AutoMod rule