A self-hosted Discord bot for community servers, built with TypeScript, Discord.js v14, and SQLite. OmegaBot combines games, progression, moderation, utility commands, and AI-assisted chat in one modular codebase.
- Runs a broad
/funcommand hub with games, reminders, polls, quotes, weather, chat, and leaderboards. - Tracks progression with achievements, shared XP/levels, and daily quests.
- Supports server utility features like FAQ, rules, welcome flows, starboard, suggestions, and status checks.
- Lets members choose approved server roles with the
/rolesslash command. - Can search curated FAQ docs plus an optional Notion wiki via
/wikiand/notion search. - Includes admin-focused health, metrics, backup, and troubleshooting support for self-hosted operation.
- Stores persistent data in SQLite so state survives restarts.
- Optional Web API — same backend can power a website (profiles, leaderboards, events, games). See Web platform and Setting up the website below.
- Community Discord servers that want games, utility, and moderation in one bot.
- Self-hosters who want a feature-rich bot they can run themselves.
- Developers looking for a larger Discord.js reference project with tests, docs, and operational tooling.
- A hosted SaaS bot.
- A minimal starter template.
- A clinical mental health product. Supportive chat exists, but it is not therapy.
git clone https://github.com/NickTheDevOpsGuy/OmegaBot.git
cd OmegaBot
npm install
cp .env.example .env # Edit with your bot token
npm run build
npm run register
npm startDocker (alternative):
cp .env.example .env # Add your DISCORD_TOKEN, DISCORD_APP_ID, DISCORD_GUILD_ID
docker compose up -dOptional — run the Web API (for a separate website using the same data):
npm run build
npm run api
# API listens on port 4000 (or set WEB_API_PORT). See docs/web-platform.md.- Games: 8-ball, RPS, Tic Tac Toe, Trivia, Blackjack, Connect 4 (persistent multi-day, continue option), Hangman, Wordle, Slots (1/3/5 rows, rare random events), Darts, Chess, Memory, Higher/Lower, Dice, Coinflip, Choose, Would You Rather
- Daily check-ins, shared XP/levels, and rotating daily quests
- Achievements and per-game stats
- Quotes, jokes, polls, reminders, and leaderboards
- DM or mention-based chat plus
/fun utility chat - Supportive chat modes, recaps, saved context, and gentle check-ins
- GitHub and service status lookups
- Curated docs lookup with
/wikiand optional Notion-backed knowledge search - Weather, timezone-aware profile info, server info, and invite helpers
- FAQ, rules, welcome handling, starboard, self-assignable roles, and suggestions
/event— Create, join, list, and manage platform events (create, update, join, list, results)/admin health, metrics, dashboard, DB backup, and DB integrity checks- Graceful shutdown, rate limiting, and resilient interaction recovery
- Designed to run as a long-lived process
- Safe to restart (state persisted in SQLite)
- Background pollers never crash the process
- Optional features auto-disable when misconfigured
- Backup: Run
npm run db:backupperiodically, or copydata/omegabot.db; see Runbook - Runtime: Node.js 18+ is supported; Node 22 is recommended (LTS), and
.nvmrcis set to22 - Web API: Optional. Run
npm run apito start the HTTP API (default port 4000). Same database as the bot. See Web platform for setting up a website.
Every Markdown file in docs/ is linked here (23 docs).
- Command Reference – Command behavior and user-facing command details
- Discord Bot Setup – Create the bot app, intents, scopes, and permissions
- Environment Setup –
.envconfiguration and optional features - Notion Wiki Setup – Connect a Notion database for
/wikiand/notion - Runbook – Deploy, restart, backup, health checks, Docker
- Troubleshooting – Common failures, interaction issues, native module mismatch notes
- Analytics – Daily game metrics and usage tracking
- Conversational Chat & LLM – Chat modes, memory, recap, supportive chat behavior
- FAQ for Server Admins – Hosting/admin questions and common operational answers
- FAQ System Design – FAQ storage model and entry format
- Localization (i18n) – Locale support and translation patterns
- Progression – Shared XP, level curve, quest rewards, and where progression appears
- Transcripts & Summaries – Transcript pipeline and summary modes
- Development Notes – Conventions, file sizing, and architectural guidance
- File & folder tree – Expandable directory tree
- Games development – Adding games, progression, result rendering, sessions
- Grafana Dashboard – Metrics visualization setup
- Project Structure – Folder layout and where major systems live
- Web platform – Shared backend for Discord + web, API, website setup steps, events, posts, profiles
- Gameplay Improvements – Play-feel and balance ideas
- Games & UX Ideas – Engagement and usability ideas
- Improvement Ideas – Maintainability, ops, and quality ideas
- Recommendations – Command and feature recommendations
analytics · chat-and-llm · commands · dev-notes · faq · faq-admins · file-structure · games-and-ux-ideas · games-development · gameplay-improvements · grafana · i18n · improvements · progression · project-structure · recommendations · runbook · setup-discord · setup-env · setup-notion · transcripts · troubleshooting · web-platform
- Runtime: Node.js 18+ (22 LTS recommended; use
nvm useorfnm useif you use a version manager) - Language: TypeScript 5.x
- Discord: discord.js v14
- Database: SQLite (better-sqlite3)
- Logging: pino
- Quality: ESLint, Prettier, Husky
- Ops: Docker, Docker Compose, Dependabot, DevContainer
Commands live under src/commands/ (core, games, social, other); services under src/services/ (core, discord, integrations, stores). Games use gameLogic.ts, ui.ts, and *Store.ts; the fun command is built from funSubcommands/ and routes via execute.ts. For a full walkthrough and an expandable file tree, see Project structure and File & folder tree.
- Fork the repository
- Create a feature branch
- Make your changes
- Run
npm run lint && npm run typecheck - Run
npm testto verify tests pass - Submit a pull request
For where things live in the repo, see Project structure, File & folder tree, and Development Notes.
npm test # Run tests in watch mode
npm run test:run # Run tests once
npm run test:coverage # Run with coverage report
npm run test:e2e # E2E: start bot, wait for Discord ready (needs DISCORD_TOKEN, DISCORD_APP_ID)
npm run check:discord # Verify discord.js is v14.x
npm run db:check # Verify SQLite database integrity
npm run db:backup # Backup database to data/backups/
npm run db:seed # Seed dev DB with sample FAQs/timezone (DATABASE_PATH=data/dev.db)
npm run dev:watch # Run with hot reload (restarts on file change)
npm run api # Start the optional Web API (see docs/web-platform.md)35+ test files (200+ tests): unit tests (games, stores, services, config, roles, rate limiting, metrics) and integration tests (dice, slots, ping, admin, help, status, config, FAQ, rules, suggestion).
This project is licensed under the MIT License. See the LICENSE file for details.