Nudge 🌱

A free, self-hosted Discord reminder bot. No subscriptions, paid APIs, or AI service required.

Note

Project Status: Nudge is currently an initial release (v1.0.0). While its comprehensive offline test suite passes (26/26 tests), the bot has not yet been live-tested in a production Discord server.

• One-time and repeating reminders in a channel or your DMs
• Done and Snooze 15 min buttons that survive bot restarts
• Per-user timezones (default: Asia/Kathmandu [GMT+5:45], configurable in .env)
• SQLite persistence, private reminder lists, and owner-only controls
• Gentle prompts to start with five minutes

Run locally

Requires Python 3.11 or newer. From this folder:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env

1. Open the Discord Developer Portal and create an application named Nudge. Discord calls bot registrations “applications”; everything you use will happen inside Discord.
2. In Bot, generate/reset the bot token and put it in .env as DISCORD_TOKEN. Keep it private; do not paste it into chat or commit it. No privileged intents are needed.
3. Under Installation, enable Guild Install. Use the bot and applications.commands scopes. Grant View Channels, Send Messages, Embed Links, and Attach Files. If using threads, also grant Send Messages in Threads. Administrator permission is unnecessary.
4. Open the installation link and add Nudge to your server. You need permission to manage that server.
5. For immediate command registration in your server, enable Discord Developer Mode, copy the server ID, and put it in DISCORD_GUILD_ID in .env. Leave this blank to register globally instead; commands can take time to appear. Server-scoped commands are used inside that server, including dm:True delivery.
6. Start the bot:

python -m nudge.bot

Try it

Use /remind and fill in Discord's option fields:

Option	Example
when	1m
text	Open my project and work for just 5 minutes
repeat	Leave blank, or use 1d for daily
dm	True for a private reminder

when accepts durations such as 15m, 2h, 1h 30m, 1d, or a date such as 2026-09-25 19:00. Dates without an offset use your configured timezone. Explicit ISO offsets are also supported. It does not parse phrases such as “tomorrow evening”.

• /timezone name:Asia/Kathmandu — set your local timezone.
• /reminders — privately list active reminders and failed deliveries.
• /cancel reminder_id:1 — cancel a reminder and its future repeats.
• /help — see examples inside Discord.

Done acknowledges that alert; it does not stop a recurring schedule. Snooze creates a separate one-time reminder 15 minutes later without moving the recurring schedule. The snoozed reminder has its own ID in /reminders; cancel it separately if needed. To reschedule, cancel the old reminder and create a new one.

For a simple daily plan, schedule “Pick 1–3 priorities” in the morning and “Review today and pick a small next step” in the evening with repeat:1d. There are no automatic follow-up pings unless you explicitly schedule a repeat or snooze.

Hosting and reliability

Running this on your own computer requires no hosting subscription. The computer must remain awake, connected, and running the bot. If it sleeps or the bot is stopped, overdue alerts are delivered when it returns. For a repeating reminder, one overdue alert is sent and missed intervals are skipped to avoid a burst of old notifications. Polling runs every 10 seconds.

Run one bot process per database. Data lives in data/nudge.sqlite3; preserve that file across upgrades and back it up while the bot is stopped. The bot uses fixed repeat intervals: 1d means 24 hours, so daylight-saving changes can move the local delivery time. For an ambiguous daylight-saving time, specify an explicit UTC offset.

Transient Discord HTTP failures retry after a minute. Missing channels or permissions mark a reminder as failed; check /reminders, fix permissions, cancel the failed item, and recreate it. Delivery and database writes cannot be one transaction: a crash immediately after Discord accepts a message may produce a duplicate on restart. Discord notification settings, muted channels, and disabled DMs can affect whether your phone alerts you.

Channel reminders are visible to everyone who can read that channel. Use a private channel or dm:True for personal plans. A DM test message is sent when creating a DM reminder to check access.

Development

.venv/bin/python -m unittest discover -s tests -v

The scheduler tests run offline. Before relying on the bot, do one live /remind when:1m test, try Snooze and Done, restart the bot, and verify /reminders still lists saved reminders. A Discord token is required for live testing.

Built with discord.py. Licensed under MIT.