Carlos - Discord Modbot & Activity Logger

A feature-rich, security-hardened Discord moderation bot written in 100% pure Go using the GoDiscord framework. Zero external dependencies.

---

Quick Start

Goal	Guide
First-time Discord setup	docs/setup/BASIC.md
Local development	docs/setup/DEV.md
Host on Railway	docs/setup/RAILWAY.md
Install on Linux	sudo bash install.sh
Install on Windows	.\install.ps1 (Admin PowerShell)

---

Feature Summary

Category	Features
Moderation	Warn, Mute (Discord timeout), Unmute, Kick, Ban, Unban, Purge
Target Resolution	All mod commands accept raw user ID, <@mention>, or username/display name prefix
Channel Tools	Slowmode, Lock, Unlock, Server Lockdown
Case Management	Full case log, Case lookup, Reason update, Case deletion
User History	Per-user infraction timeline with timestamps
Admin Tools	Role management, role-restore on rejoin, log channel routing, mod statistics, bot-noise filter
Audit Feeds	Staff (detailed), User (public), Mod case log, Server/system, Join, Message, Link
Event Logging	Message edit/delete, Bulk delete with author breakdown, Join (with new-account flag), Leave (with roles + time-in-server), Role changes, Nickname changes, External bans/unbans/timeouts, Command denials, Rate-limit hits, Hierarchy blocks, Config changes, Bot lifecycle
Noise Suppression	Four-tier bot-noise filter (prefix list, channel allow-list, content auto-detect, short-lifetime timing heuristic) plus audit-log-based confirmation for silent-delete bots
Help System	!help prefix command - ephemeral, staff-only, tiered select-menu
Security	4-tier RBAC, hierarchy enforcement, rate limiting, ban-spree detection
Deployment	Docker + Railway ready, self-contained vendor build

---

Access Tiers

Tier	Who	Access
Owner	BOT_OWNER_IDS in env	Bypasses all checks - every command
Admin	Members with an Admin role	All mod + admin commands
Mod	Members with a Mod role	All moderation commands
User	Everyone else	None

---

Commands at a Glance

Moderation (Mod+)

All user-targeting commands accept a raw ID, <@mention>, or a username/display name prefix.

!warn <user> [reason]         Issue a formal warning (DMs target, creates case)
!mute <user> <dur> [reason]   Discord timeout - 10m, 2h, 1d, max 28d
!unmute <user>                Remove an active timeout
!kick <user> [reason]         Kick (DMs target first)
!ban <user> [days] [reason]   Ban - days = message history to delete (0-7)
!unban <userID> [reason]      Lift a ban
!purge <count>                Bulk-delete 1-100 messages
!slowmode [seconds]           Set channel slowmode (0 = off)
!lock [reason]                Deny @everyone SEND_MESSAGES
!unlock                       Restore send permissions
!modlog <user>                View full infraction history
!note <user> <text>           Add a private staff note
!case <id>                    Look up a case by short hex ID
!reason <id> <new>            Update a case reason

<user> accepts any of:

• Raw snowflake: 123456789012345678
• Discord mention: <@123456789012345678>
• Username or display name prefix: someuser or @someuser

Administration (Admin+)

!setlog <type> [#channel]     Configure log channel - types: staff user modlog join msg link server
!setmodrole @role             Toggle a Mod role (run again to remove)
!setadminrole @role           Toggle an Admin role
!clearcase <id>               Permanently delete a case
!clearwarn <user>             Clear all warnings for a user
!modstats [user]              Mod action leaderboard (or single-mod stats)
!config                       Show current bot configuration
!rolerestore on|off           Toggle role restore for users who leave and rejoin
!lockdown [reason]            Lock ALL text channels
!unlockdown                   Restore lockdown channels
!botfilter                    Manage the bot-noise filter (prefix/channel/auto)
!help                         Ephemeral help panel with tiered select-menu

Role restore

When !rolerestore on is set, Carlos saves a member's roles when they leave and reapplies them when they rejoin. Useful for preventing role-bypass by leaving and rejoining. Toggle per guild - off by default.

Bot-noise filter

Carlos keeps the message-edit/delete log clean in servers that host third-party bots (music, utility, gambling, etc.) by suppressing events that clearly belong to another bot's command handler. Four tiers run in order; the first match wins:

1. Prefix list - !botfilter prefix add - marks - as another bot's command prefix. Messages starting with it are hidden from the msg log on delete/edit.
2. Channel allow-list - !botfilter channel add #bot-commands silences the entire channel (and its threads). Useful for dedicated bot-command channels.
3. Content auto-detect - !botfilter auto on lets Carlos correlate punctuation-prefixed user messages (".n dice 1 100") with recent bot activity in the same channel and treat them as cleanup noise.
4. Short-lifetime heuristic - user messages that only existed for a few seconds in a channel with recent bot activity are assumed to be bot command cleanup regardless of shape. Catches prose-style command surfaces ("Dice 1 100", "roll 2d20", "buy lambo").

An audit-log fallback runs for any event that survives all four tiers, confirming the actual deleter via Discord's audit log. It requires the View Audit Log permission on Carlos's role; without it the audit fallback silently skips and the event is logged normally.

Run !botfilter with no arguments to see the current settings for a guild.

---

Architecture

Carlos/
+-- main.go                    Entry point
+-- Dockerfile                 Multi-stage build (scratch runtime ~8 MB)
+-- railway.toml               Railway deployment config
+-- vendor/                    Vendored GoDiscord (self-contained - no network needed)
|
+-- internal/
|   +-- config/                Environment-variable loading
|   +-- store/                 JSON-persisted guild data (infractions, config, stats)
|   +-- access/                4-tier RBAC with hierarchy enforcement
|   +-- audit/                 Dual-feed audit dispatch + pluggable sinks
|   +-- ui/                    Embed builders, colour palette, duration parser
|   +-- security/              Rate limiting + ban-spree detection
|
+-- bot/
    +-- setup.go               Carlos struct, event wiring, two-phase embed animation
    +-- mod.go                 Moderation commands
    +-- admin.go               Admin commands (roles, log channels, botfilter)
    +-- help.go                !help prefix command + dropdown router
    +-- logger.go              Passive event loggers (edit/delete, join/leave, etc.)
    +-- botfilter.go           Four-tier bot-noise suppression for the msg log
    +-- interactions.go        INTERACTION_CREATE router

---

Security Highlights

• Hierarchy enforcement - mods cannot target users of equal or higher tier
• Rate limiting - 20 actions per 5 minutes per moderator
• Ban-spree detection - 5 bans in 2 minutes triggers a staff @here security alert
• Owner protection - bot owners cannot be moderated; their IDs live in env, not Discord
• Select-menu hardening - component custom_id values are allowlisted (help:* prefix)
• Immutable case log - only admins can delete cases; mods cannot modify their own records

---

Self-Hosting (Docker)

docker build -t carlos .
docker run -d \
  -e DISCORD_TOKEN=your_token \
  -e BOT_OWNER_IDS=your_user_id \
  -v carlos-data:/data \
  --name carlos \
  --restart unless-stopped \
  carlos

See docs/setup/RAILWAY.md for one-click cloud hosting.