Skip to content

Home

Jump to bottom
Johnny Xmas edited this page Sep 22, 2026 · 7 revisions

JohnnyBot - The Missing Discord Server Management Toolkit

Welcome to the JohnnyBot wiki! JohnnyBot does all of the stuff Discord bizarrely won't let you do! Designed to automate tons of server management and enforce some rules while you're at it.

Quick Navigation

What is JohnnyBot?

JohnnyBot provides features such as automatic role assignment, message deletion, and user management to ensure a smooth server experience. Most commands require the Manage Messages permission — no role to create or name, so it works on any server the bot joins with zero setup. Server backup/restore commands require the stricter Administrator permission. PetBot commands can be leveraged by all users.

Key Features

Command-based Moderation

  • Provides moderators with slash commands to manage members, messages, and post announcements
  • Mass role assignment for efficient user management

Server Backup & Restore

  • /server_backup snapshots roles, categories, channels, permission overwrites, and emoji to a JSON file DMed to you
  • /server_restore replays a backup with a preview, an explicit confirm step, and an automatic pre-restore safety snapshot — matches existing objects by name so it's safe to run more than once
  • /auto_backup runs backups on an interval, but only actually creates one when the server's structure changed since the last one
  • Requires Administrator; never touches Administrator/managed/above-hierarchy roles or grants moderation-level permissions, even from a hand-edited backup file

Raid Protection

  • A burst of joins (default 6 in 30 seconds) pauses invites and member-to-member DMs and alerts moderators
  • Uses Discord's own incident actions, which expire on their own — no timer to survive, and a bot restart mid-raid changes nothing
  • The alert includes an avatar-cluster breakdown ("12 of 14 share one image"), since bulk-created raid accounts reuse profile pictures — that's what separates a raid from a legitimate surge of arrivals
  • /raid recent_joins and /raid kick_recent (dry run by default) for review and cleanup; /raid lockdown for manual control

Anti-Nuke Protection

  • Watches the audit log for a compromised moderator account or rogue integration — the case the bot's own commands can't see, because the attacker acts directly against the Discord API
  • Triggers on a destructive burst (channel/role deletes, kicks, bans, webhook creation), a member prune, or any grant of a dangerous permission
  • Strips the offending account's roles and reverts the permission change itself — neutralizing the actor while leaving the alt account holding administrator would mean the attack still succeeded
  • Reversible by design: a moderator restores the account with /assign_role in seconds if it's a false alarm. Deliberately not a kick

Message Spam Protection

  • Catches what a raid does once inside: the same link blasted across several channels, and mass pings
  • Link detection is behavioral, not a domain blocklist — scam domains burn within days, so a list is stale before it ships, while the cross-posting pattern holds whatever the domain is
  • Deletes every copy, times the offender out, or kicks them if the account is under two days old

See Safety Systems for detection details, thresholds, tuning guidance, and the bot permissions these need.

Direct Messages

  • Anyone who DMs the bot is kicked from every server they share with it, and the kick is reported to the moderators channel
  • Exempt: users with the Manage Messages permission, and anyone the bot DMed in the last 24 hours (so replying to a /message_dump archive or /log_tail output is safe)
  • Separately, no slash command can be invoked in a DM — every command requires a server context, so Discord simply won't offer them there

Voice Channel Chaperone

  • Monitors voice channels and mutes all members if only one adult and one child are present
  • Sends a single alert to the moderators channel per incident
  • Lifts the mute automatically once the channel is no longer one adult and one child, when a muted member moves to a safe channel, or when the feature is disabled — outstanding mutes are persisted to chaperone_mutes.json so they survive a bot restart
  • Only mutes the bot applied are lifted; a manual moderator mute is never undone

Reminder System

  • Set recurring reminders to be sent to specific channels at regular intervals
  • Persistent reminder storage with automatic scheduling

Event Feed Integration

  • Subscribe to calendar (iCal) or RSS feeds (including Meetup.com) and automatically create Discord Scheduled Events
  • Per-feed announcement channel configured when the feed is added
  • Automatic schedule: weekly feed check (Monday 9am), "This Week" preview (Monday 10am), and day-of reminders (Tuesday–Sunday 10am; Monday is skipped because the weekly preview already covers it) — timezone configurable via BOT_TIMEZONE

Logging and Notifications

  • Logs actions and errors to a rotating log file in the bot directory
  • Moderators can DM themselves a tail of the log with /log_tail

Message Archive

  • Allows moderators to dump and archive user messages from specific channels
  • Delivers the archive as a zipped file via DM (25 MB Discord attachment cap)
  • Automatically cleans up old archive files

Channel Write Protection

  • Deletes any non-moderator messages posted in the PROTECTED_CHANNELS you define in your config.py (copied from config_example.py)
  • This is a hack to get around Discord's requirement of a minimum number of messageable channels

PetBot Interactions

  • Includes PetBot functionality with time-themed messages

Requirements

  • Python 3.11+ — tested on 3.11, 3.12, 3.13, and 3.14 in CI. The bot's dependencies technically allow 3.10, but 3.10 reaches end-of-life in October 2026, so 3.11 is the supported floor.
  • All modules in requirements.txt

Getting Started

  1. Follow the Setup Guide for complete installation instructions
  2. Browse the Commands Reference to learn about available commands
  3. Configure your bot according to your server's needs

Concurrency Model

Important: The bot is asyncio-first, with threading used narrowly for state a background scheduler job can touch outside the event loop. DO NOT CHANGE THIS:

asyncio is used for:

  • All Discord API interactions (primary event loop)
  • Recurring work — feed checks, event announcements, reminders, auto-backups, update checks — which run as jobs on a single shared AsyncIOScheduler, not as separate threads
  • Command handling and network operations
  • Blocking file writes are pushed off the loop with asyncio.to_thread rather than made synchronous inline

threading is used for:

  • threading.Lock() guarding a small number of dicts written from more than one place (autoreply rules, auto-backup configs, per-feed state) — not a general-purpose cache

This keeps the bot to one event loop with no background threads of its own, while still protecting the handful of dicts that scheduler jobs and command handlers can touch concurrently.

Contributing

Contributions are welcome! If you encounter any bugs or have suggestions, feel free to open an issue or submit a pull request on the GitHub repository.

Attribution

Bot interaction functionality adapted from PetBot under MIT License.

License

This project is licensed under the GNU General Public License v3.0.

Clone this wiki locally