Zentrynel

A sharding-ready Discord moderation bot with an escalating strike system, built with Bun and discord.js v14. Protect your community with slash commands, automatic escalation, and per-server configuration out of the box.

Features

• Slash commands — /warn, /mute, /kick, /ban, /purge, /warnings, /approve, /config.
• Escalating strike system — Configurable per-server thresholds that auto-mute, kick, or ban.
• Two-layer member verification — In-server button + challenge flow with manual moderator fallback queue, auto-kick for stale unverified members, and manual review expiry.
• On-join role — Automatically assign a role to new members on join, independent of verification.
• Sharding-ready — Separate shard manager and client entry points, scales to thousands of servers.
• Swappable database — Abstracted DB layer on better-sqlite3, swap to PostgreSQL with one import change.
• DM & invite disabler — Disable member-to-member DMs and/or invite creation server-wide, automatically maintained.
• Per-server config — Each server gets independent settings, log channels, and strike history.

Setup

bun install
bun run build
cp .env.example .env

Fill in your .env:

DISCORD_TOKEN=your_bot_token
CLIENT_ID=your_application_client_id
DEV_GUILD_ID=your_test_guild_id  # optional, for instant command registration

Invite the bot to your server (replace YOUR_CLIENT_ID with your application client ID):

https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=1101927640118&integration_type=0&scope=bot+applications.commands

Usage

# Register slash commands (guild-scoped if DEV_GUILD_ID is set)
bun run register

# Start the bot with sharding
bun run start

# Development mode (single shard, hot reload)
bun run dev

Commands

Command	Permission	Description
/warn <user> [reason]	Moderate Members	Issue a warning
/mute <user> [duration] [reason]	Moderate Members	Timeout a user
/kick <user> [reason]	Kick Members	Kick a user
/ban <user> [reason] [delete_messages]	Ban Members	Ban a user
/purge <amount> [user]	Manage Messages	Bulk delete messages
/warnings <user>	Moderate Members	View active warnings
/approve <user> [reason]	Moderate Members	Manually approve a member's verification
/config view	Administrator	View server settings
/config logchannel <channel>	Administrator	Set mod log channel
/config thresholds [mute] [kick] [ban]	Administrator	Set strike thresholds
/config muteduration <duration>	Administrator	Set default mute duration
/config onjoinrole [role]	Administrator	Set or clear the auto-assigned on-join role
/config verificationenable <enabled>	Administrator	Enable/disable member verification
/config verificationchannels <verify> <review>	Administrator	Set verify and review channels
/config verificationroles <verified> <unverified>	Administrator	Set verified/unverified roles
/config verificationrules [minage] [maxattempts]	Administrator	Set account-age (e.g. 24h, 2d) and retry rules
/config verificationpanel	Administrator	Post verification button panel
/config verificationkick [timeout]	Administrator	Auto-kick unverified members after a timeout
/config manualreviewtimeout [timeout]	Administrator	Auto-expire manual reviews after a timeout
/config disabledms <disable>	Administrator	Disable or re-enable DMs server-wide
/config disableinvites <disable>	Administrator	Disable or re-enable server invites
/config reset	Administrator	Reset to defaults

Escalation

Warnings automatically escalate based on per-server thresholds:

Threshold	Default	Action
Mute	3 warnings	Auto-timeout
Kick	5 warnings	Auto-kick
Ban	7 warnings	Auto-ban

Server admins can customize these via /config thresholds.

Member Verification

Verification is fully in-server (no DMs):

1. Configure verification using:
   • /config verificationenable enabled:true
   • /config verificationchannels verify:<channel> review:<channel>
   • /config verificationroles verified:<role> unverified:<role>
2. Post the verification panel with /config verificationpanel.
3. New members get the unverified role on join.
4. Members click Start Verification in the verify channel:
   • If automated checks + challenge pass, bot grants verified role.
   • If risk/failure is detected, bot queues member in review channel for moderator action.
5. Moderators can approve, kick, or ban members directly from the review embed, or use /approve <user> to manually verify a member.

Verification Automation

• Auto-kick unverified members — /config verificationkick timeout:1h kicks members who don't complete verification within the specified duration. Omit the timeout to disable.
• Manual review expiry — /config manualreviewtimeout timeout:3d auto-expires stale manual reviews and kicks the member. A reminder is sent before expiry. Omit the timeout to disable.
• Verification honeypot — /config verificationhoneypot enabled:true deletes posts in the verify channel, warns the member for three minutes, then permanently bans another post made within 24 hours. The bot needs Ban Members, View Channel, Manage Messages, Send Messages, and Embed Links there. Use enabled:false to disable it.

On-Join Role

Automatically assign a role to every new member when they join the server:

• /config onjoinrole role:@NewMember — Set the auto-assigned role.
• /config onjoinrole — Clear the on-join role (omit the role option).

The on-join role is independent of verification. If verification is enabled, the on-join role is removed when a member is verified or rejected.

DM & Invite Disabler

Disable member-to-member DMs and/or server invites using Discord's Incident Actions API:

• /config disabledms disable:true — Disables DMs server-wide.
• /config disableinvites disable:true — Disables invite creation server-wide.
• Pass disable:false to re-enable either setting.

Discord limits the disable window to 24 hours. The bot automatically re-extends the restriction every 12 hours so it stays permanent until you turn it off.

Note: Friends can still message each other, moderators can still message members, and bots/apps are unaffected. This only restricts regular member-to-member DMs within the server context.

Architecture

src/
├── index.ts            # ShardingManager entry point
├── bot.ts              # Per-shard client
├── commands/           # Slash commands (auto-discovered)
├── events/             # Event handlers (auto-discovered)
├── handlers/           # Command/event loaders, command registrar
├── services/           # Moderation, verification, mod log, sweeps
├── db/                 # Abstracted database layer
├── config/             # Environment, constants
└── utils/              # Logger, embeds, permissions, time parsing

Development

bun install
bun run dev
bun run lint
bun run format

License

GPLv3 — WG Tech Labs