A powerful time-based bot allowing you to create detailed timers, alarms, and reminders in your Discord server effortlessly.
Warning
This project is currently in its beta state as I monitor for bugs and gather user feedback. If you encounter any issues, please report them here :)
- (⏱️) Create precise timer countdowns with hours, minutes, and seconds.
- (⏰) Schedule alerts for specific dates and times in your local time zone.
- (📝) Add titles and descriptions to your alarms to be notified of your upcoming events, goals, and more!
- (💾) Save timer configurations with custom names for quick access anytime.
- (📋) Manage all your running timers, alarms, and reminders in one place.
- (🌐) Set your local time zone for accurate alarm scheduling.
- (🔔) Choose users or roles to notify when an event ends.
To start using Timer Bot in your Discord community, you can invite the bot to your server here.
Once added, you can type / followed by one of the commands below:
/timer: Set a custom timer with hours, minutes, and seconds./alarm: Set an alarm that goes off at a specific date and time./reminder: Set a detailed reminder with a title and description./presets create: Create a reusable timer preset for future use./presets run: Run a previously saved preset by its custom tag./list events: View all active timers, alarms, and reminders./list presets: View all saved timer presets./timezone: Set your time zone for accurate reminders and alarms./status: Check the bot's uptime, memory usage, and server count./vote: Support Timer Bot by voting on Top.gg and others!/support: Join the Timer Bot support server for help.
Tip: you can use the /help command to view this list at any time!
Note
Self-hosting is optional and intended for developers or advanced users who want more control. Most users won't need to self-host.
Warning
Before starting the bot, make sure you have a valid config.json file containing your configuration (such as your Discord bot token, or PayPal API credentials). For Docker, this file should be placed in the folder you're mounting (e.g., ./data).
Prefer to host the bot yourself? Timer Bot is open-source under the Apache 2.0 license, and is easy to set up on your own server.
To start, you can download this repository by using the following:
git clone https://github.com/BrianWalczak/TimerBot.git
cd TimerBotWhen hosting Timer Bot, it's highly recommended to run it inside a Docker container to keep it isolated from your main machine.
To do this, start by building the image using the provided Dockerfile:
docker build -t timerbot .Once the image is built, you can run the bot with docker run or edit the docker-compose.yml template included.
services:
app:
image: timerbot
container_name: timerbot
ports:
- "3000:7000" # Exposes port 7000 from the container to port 3000 on your host (change 3000 if needed)
volumes:
- ./data:/usr/src/app/data # Replace './data' with the path to your local config.json and database files
environment:
CONFIG_FILE: /usr/src/app/data/config.json # Path to your server configuration file
DATABASE_URL: file:/usr/src/app/data/data.db # Location for your Prisma database file
restart: unless-stoppedIf you prefer to run Timer Bot on your local system, that's fine too! Just make sure that Node.js is properly installed (run node --version to check if it exists). If you don't have it installed yet, you can download it here.
Next, install the required dependencies and start the bot:
npm install
npm run start # already migrates + generates PrismaCaution
Starting with Timer Bot version 3.1.0, the database backend has switched from LokiJS to Prisma + SQLite. This means your old data stored with LokiJS will NOT be automatically migrated. Please back up your existing data and run the interactive migration helper script to transfer your data (npm run db/loki-migrate).
Timer Bot uses both the built-in Date object in Node.js and the luxon library for handling time calculation. To maintain consistency and avoid issues with timezone (such as conversion to the local server time), it relies on Unix epoch timestamps, which represent time in UTC. This ensures all times are standardized to UTC regardless of the server's local timezone. For alarms and reminders, which require a date and time input, Timer Bot uses luxon to correctly handle the event data with the user's local timezone.
Before any event is stored in the database, all event types are converted to milliseconds (Unix epoch timestamps), ensuring every stored time is in UTC.
If you'd like to contribute to this project, please create a pull request here. You can submit your feedback or any bugs that you find on the issues page. Contributions are highly appreciated and will help us keep this project up-to-date!