🤖🟣 A general use-case discord bot

1. Create an application in the Discord Developer Portal.
2. Go to the Bot page and select the correct toggles.
3. Go to OAuth and select Bot in the check boxes.
4. Then select Admin.
5. Copy the URL and add to a server.

1. Install uv from https://docs.astral.sh/uv/.
2. Install dependencies with uv sync.

python3 main.py

To enable the >update command (git pull + restart), launch via the wrapper instead:

./run.sh

The wrapper relaunches the bot when it exits with code 42, which is what >update does after pulling. Set admin_id in bot.toml to the Discord user ID allowed to run >update.

Ping a computed set of members using set-algebra expressions.

Slash command (recommended):

/ping expression:<expr> message:<text>

The expression field has autocomplete — type a role name or @here and select from the dropdown. Operators (&, |, ^, !) must be typed manually between selections.

/ping expression:@here & Rusty Minecraft message:can someone review my PR
/ping expression:@here | Mods message:Hey there!
/ping expression:!(@here) message:you all missed it

Operands:

Operators (loosest to tightest precedence):

Bots are never pinged. @here requires the Presence Intent enabled in the Discord Developer Portal.

>activity [limit]

Shows message counts per member in the server. limit defaults to 1000 messages scanned.

>birthdays
>birthday channel check

Lists everyone's birthday (channel-restricted). >birthday channel check sends a test message to the configured announcements channel.

Configure birthdays in birthdays.toml:

birthdays = [
  { month = 1, day = 23, user_id = 12345, name = "Ubik" },
]

Notification streams are configured in notification_streams.toml. Each stream points to a Python script implementing:

def get_new_events() -> list[str] | list[dict]: ...

The script handles deduplication so only new events are returned each run. The bot checks streams once daily.

>notify list                          — list available streams
>notify signup <stream> [dm|channel]  — subscribe
>notify unsubscribe <stream>          — unsubscribe
>notify run                           — manually trigger all streams

>latex <expression>

Renders a LaTeX expression as an image. Example: >latex e^{i\pi} + 1 = 0

>kronicler

Shows a runtime plot from kronicler data.

>commit   — show the latest git commit hash and date
>source   — show the GitHub repository link
>link     — show the bot invite link
>update   — git pull and restart (admin only)
>eval     — evaluate Hy (Lisp) code (admin only)