A friendly, self-hosted Discord bot for a friends' server. It started with opt-in ping roles:
members tap buttons in #roles to choose which pings they get (movie nights,
streams, game days…), so the server can stop using @everyone for everything.
It also has optional features you switch on when you want them: movie nights (watchlists,
polls, ratings and a history), birthdays, event reminders, game day sign-ups, event attendance, stream
alerts, welcome and approval, and a mod log.
- Swappable personality: announcements and replies come from a persona file, so you can rename it or change its voice without touching code. The default, Pingwin, is a playful penguin: puns in announcements, plain words in mod tools and errors.
- Runs on several PCs: one answers, the others wait on standby and take over if it goes offline.
- Updates itself from GitHub.
- Dashboard in your browser for settings, status and logs.
📘 New to Pingwin? Follow the setup guide. It covers everything from creating the bot in Discord to posting your first menu, plus troubleshooting.
The short version, on a Windows PC that stays on:
- Create a bot in the Discord Developer Portal, copy its token, and
invite it with
https://discord.com/oauth2/authorize?client_id=APP_ID&scope=bot+applications.commands&permissions=2815033570708480. - Install Python 3.11+ and Git, then
git clone https://github.com/brandonbtm29/Pingwin.git. - Double-click
scripts\setup.cmdand paste your token when asked. - Double-click
scripts\run_pingwin.cmd, thenscripts\open_dashboard.cmd, and follow the Setup tab's checklist. - Optional:
scripts\install_autostart.cmdstarts Pingwin in the background (no window) when you sign in, and adds a Pingwin Dashboard shortcut to your desktop. Stop it with Status → Stop Pingwin. - Optional: to let people rate movies by voice message, also run
.venv\Scripts\python -m pip install -e ".[voice]"in the Pingwin folder (on every PC that may answer). See Rate by voice.
Every command lives under /pingwin, so it doesn't get mixed up with other bots' commands.
| Command | Who | What |
|---|---|---|
/pingwin rolemenu setup |
Manage Roles | Creates missing menu roles (pingable, no permissions) and checks the rest |
/pingwin rolemenu check |
Manage Roles | Same report, changes nothing |
/pingwin rolemenu post [channel] [menu] |
Manage Roles | Posts a button menu (the ping menu, or another one like time zones) |
/pingwin rolemenu refresh |
Manage Roles | Updates posted menus in place after you change the roles |
/pingwin timezone set · show · remove |
Everyone | Pick your time zone, so times you type mean your time |
/pingwin about |
Everyone | Says hi |
/pingwin status |
Everyone | Which PC is answering, version, uptime |
/pingwin dashboard |
Manage Server (or the dashboard admin role) | Links to the dashboard (when it's online) |
/pingwin reload |
Manage Server | Reload settings now (they also reload on their own within a minute) |
/pingwin restart |
Manage Server | Restart and install any update from GitHub |
Only members with the Friend role can use the menus (required_role in config.toml). Besides the
ping menu you can add more menus, each its own message, such as a time zone menu where picking a
role also sets that person's time zone. A menu can let people pick any number of roles, or just one.
Eight optional features, all off until you switch them on in the dashboard's Features tab. How to set them up
| Feature | Commands | What it does |
|---|---|---|
| Event reminders | (automatic) | Pings the roles whose keywords match a new Discord Event, reminds before it starts, and keeps repeating events at their local time when the clocks change |
| Birthdays | /pingwin birthday set · remove · upcoming (mods: set_for · remove_for · add_other · remove_other) |
A shout-out on the day; optional birthday role; a ⭐ Star birthdays message for people without Discord |
| Movie night | /pingwin movie nominate · list · remove · poll · endpoll · watched · tonight · history · rate · page · queue · franchise · skip · unskip |
Watchlists, Discord or ranked-choice polls, franchise queues, weeks off, a "did it happen?" card for the movie mods, a Rate it button (typed or by voice message) with a question game, and movie pages (history, ratings, stats) |
| Game day sign-ups | /pingwin gameday create · cancel |
"Who's in?" buttons and a reminder to everyone who's in |
| Event attendance | /pingwin attendance add · remove · code · history |
Takes attendance at Discord Events (voice or an "I'm here" button) and pays a reward into UnbelievaBoat |
| Stream alerts | (automatic) | Posts once when a streamer goes live on Twitch, YouTube or Discord (Go Live) |
| Welcome and approval | (buttons) | Welcomes new members; mods click Approve to give them Friend |
| Mod log | (automatic) | Joins, leaves, bans, role changes and deleted messages (edits too, if you want), in a private channel |
Admins decide how movie night works: who can nominate, who can start polls, where polls go, how the poll's movies are picked, how long it runs, and what happens on a tie. Welcome and the mod log need privileged intents (details).
Double-click the Pingwin Dashboard desktop shortcut (or scripts\open_dashboard.cmd; make the shortcut
with scripts\create_shortcuts.cmd). It starts Pingwin in the background if needed, and opens a page in your
browser with six tabs:
- Status: which PC is answering, Discord connection, version; reload, restart, check for updates, stop; remote access
- Role menu: several menus (pings, time zones, ...); add, remove and reorder roles, set emoji and descriptions, choose who can use them, see which roles are ready, create missing ones, and post menus
- Features: switch on and set up the optional features, plus event attendance, the birthday list and the movie watchlists
- PCs & failover: turn failover on, pick the status channel, order the PCs, add a backup PC
- Setup: a checklist of what's done and what's left, a check that Pingwin can reach every channel and role it's been given, and an About page
- Logs: this PC's recent log, live
Long pages have an On this page list in the empty space on the left (a ☰ Sections button on smaller screens) to jump to any section, with Expand all and Collapse all. Every section folds up with the ▾ next to its title, and each browser remembers what you folded. The movie pages work the same way.
Every PC running Pingwin has its own dashboard. Changes save to the shared config.toml, so they reach
every PC. The page only answers on that PC (127.0.0.1:8787; change it under [dashboard]), and
open_dashboard.cmd signs you in with a key kept in the project folder.
Co-admins can use it from anywhere too: put it online with Tailscale Funnel and they sign in with Discord (Manage Server or a role you pick), with nothing to install. Members (with the Friend role) can sign in there too, but only get the movie pages. Remote dashboard and co-admins. When several people have it open, it shows who's where, stops a save that would overwrite someone's newer change, and helps sort out SyncThing conflicts.
| Where | What | Synced? |
|---|---|---|
Settings folder (e.g. SyncThing\Pingwin) |
config.toml, secrets.env (token and API keys), personas\, menus.json, and state\ (what the features keep: birthdays, watchlists, the movie library, ...) |
Yes: same on every PC |
Project folder .env |
PINGWIN_DATA (path to the settings folder), PINGWIN_NODE (this PC's name) |
No: one per PC |
Project folder logs\, .dashboard-key, .dashboard-sessions.json, models\ |
Log, dashboard sign-in key, Discord sign-ins, the speech-to-text model (if voice ratings are installed) | No |
| GitHub | The code | Pulled by every PC |
Every PC connects to Discord, but only one answers at a time. The active PC checks in every 30 s by editing a status message in a mod-only channel. If check-ins stop for 2 minutes, the next PC in the list takes over. When a PC higher in the list comes back, it takes the job back as soon as SyncThing has brought its copy of the shared folder up to date.
- Make a mod-only channel such as
#pingwin-status, and let Pingwin view and post in it. - In
config.toml, list the PCs in order of preference:To add another PC later, add its name to the end of the list. A PC that isn't listed still helps, but only when every listed PC is offline.[failover] enabled = true status_channel_id = 123456789012345678 pcs = ["MAIN-PC", "FRIENDS-PC"] # 1st choice, then backups in order
- Add each backup PC with Add a backup PC on the same tab: send your friend the invite message, and paste back the reply code their installer shows. Adding a backup PC
- Share the SyncThing settings folder with that PC.
A backup only helps with internet outages if it's on a different network (e.g. a friend's house). Anyone running a backup has the bot token, so only use PCs you trust.
- Code: push to GitHub. Every PC checks every 30 minutes (
[updates] check_minutes), restarts, pulls, and reinstalls. For an immediate update on the active PC, run/pingwin restart. PCs with uncommitted code changes skip auto-updates, and a PC only installs commits signed with a key in.github/allowed_signers(see Signing commits); the Status tab says when it's holding one back. - Settings: edit
config.tomlor a persona on one PC. SyncThing copies it, and every Pingwin reloads it within a minute. After changing the menu, click Update posted menus (or/pingwin rolemenu refresh). - Personality: copy
personas\pingwin.tomlinto the settings folder'spersonas\, rename it (e.g.pirate.toml), rewrite the lines, and setpersona = "pirate".
See CHANGELOG.md for what changed in each version.
See CONTRIBUTING.md. In short:
.venv\Scripts\activate
pre-commit install # once: blocks secrets and lints each commit
pytest
Each feature lives in src/pingwin/cogs/ as its own module. Anything that runs on a timer
(reminders, polls) must check bot.is_active so standby PCs stay quiet.
- Movie-night polls, event reminders, game day sign-ups, stream alerts (0.7.0)
- Birthdays, welcome and approval, mod log (0.7.0)
- Persona switching from Discord
- AI personality (much later)
With the default features, Pingwin can't read messages and has no tracking. It keeps a small activity log (who opted into which role) on the PC that runs it. The mod log, if you turn it on, can read messages so it can record deletes (and edits, if you want). Movie night's voice ratings only listen to voice messages sent to Pingwin, turn them into text on that PC, and don't keep the recording. See the privacy notice.
MIT