DiscordBot

A small personal Discord bot I run for my own ARCS/club-related automation and utilities.

This is not a team-maintained project (at least right now). It’s mostly here so future me doesn’t hate current me, and so I can iterate safely with version control while deploying on my own server.

Current status:

• Boots and connects
• Provides a basic /ping slash command (smoke test)
• Responds to @mentions with configurable event handlers (default: "Someone say my name?")
• Gemini API integration for @mention questions (who/what/why/how/where + ?)
• Discord Chat Exporter (DCE) CLI via /DCE-<command> slash commands

The repo starts intentionally minimal. The goal is a stable foundation first, then features (like chat replay) once the dev/deploy loop is smooth.

---

Quickstart (Local / LXC)

1) Create a virtual environment

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2) Create .env

Copy the example and fill in values:

cp .env.example .env

3) Run

python3 bot.py

---

Environment Variables

Stored in .env (never commit .env).

• DISCORD_TOKEN — bot token from the Discord Developer Portal
• GUILD_ID — server (guild) ID (optional; recommended for faster slash command updates during development)
• ADMIN_CHANNEL_ID — private channel ID used to restrict admin commands (planned)
• OWNER_USER_ID — my Discord user ID used to restrict admin commands (planned)
• GEMINI_API_KEY — Google Gemini API key for @mention question handling (optional)

---

Troubleshooting

Slash commands (e.g. /ping) don’t show up

The bot must be invited with the applications.commands OAuth2 scope. If it was added without it, slash commands will never appear.

Fix:

1. Remove the bot from your server (Server Settings → Integrations → click the bot → Remove).
2. In the Discord Developer Portal, open your application → OAuth2 → URL Generator.
3. Under Scopes, select bot and applications.commands.
4. Under Bot Permissions, choose what you need (e.g. “Send Messages”).
5. Copy the generated URL and open it in a browser to re-invite the bot.

The invite URL should look like: https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=...&scope=bot%20applications.commands

@mentions don’t trigger responses

The bot needs the Message Content Intent to read messages. In the Discord Developer Portal, open your application → Bot → enable Message Content Intent.

---

Etiquette (Solo Version)

Even though this is currently a solo project, I’m using basic “team-style” hygiene so it stays maintainable and scalable.

Cloud Etiquette (Gitea)

• Create an Issue for most changes (when practical)
  • Issue titles should be 2–3 words
  • Include a description of what the change should accomplish
  • Labels are encouraged to keep things organized
• Create Pull Requests (PRs) to merge branches into dev or main
  • Reviews are optional (solo project), but PR descriptions should still be clear:
    • what changed
    • why it changed
    • how to test it
• Prefer an Issue + Branch + PR trio unless:
  • the issue is labeled won't-fix or duplicate and closed

Branch Etiquette

• main
  • Stable / “good” code
  • ONLY receives merges from dev
  • Do NOT branch off main
• dev
  • Integration/testing branch
  • All feature/bugfix/chore branches branch off dev
  • Before merging to main, ensure:
    • no hardcoded magic numbers (put into config/constants)
    • explanatory comments where needed
    • code is functional and tested
• feat#[Issue#]-[Name]
  • New features
  • CamelCase name
  • Example: feat#42-UpdateCommand
• bugfix#[Issue#]-[Name]
  • Fixes a bug found in dev
  • CamelCase name
  • Example: bugfix#27-RebootCommand
• chore#[Issue#]-[Name]
  • Cleanup, refactors, comments, formatting
  • CamelCase name
  • Example: chore#34-AddingComments

Code Etiquette

• Avoid hardcoded values; use config/constants
• Constants should be ALL_CAPS with underscores: VAR_THIS_1
• Comments should describe:
  • intent, parameters, returns (when not obvious)
• Keep related files in related folders; create new folders for new topics

---

Notes

• This bot uses slash commands (/ping). Message content intent is required for @mention responses.
• @mentions trigger event handlers; slash commands are the only way to run commands.
• DCE CLI is fetched by /bot-update and placed in src/tools/DCE. Bot-compatible commands only: export, exportguild, channels, guilds, guide. Use /dce-guide for help.
• Future features (chat replay, admin tools) will live in src/commands/.