- name
- discord-purge-bot
- description
- Operate a Discord message cleanup workflow with an official bot token and Discord HTTP API. Use when asked to purge guild channel history, delete messages by user/keyword/time window, run dry-run previews, execute guarded bulk deletion jobs, or recreate a channel for fast wipe. Do not use for self-bot cleanup or personal DM history wipe.
Discord Purge Bot
Run controlled cleanup in Discord guild channels with safety gates and audit-friendly outputs.
Safety Contract
- Use only a bot token (
DISCORD_BOT_TOKENor--token). - Refuse user-account token flows and self-bot behavior.
- Run
purge-preview.mjsfirst for every destructive request. - Require explicit confirmation code before running deletion.
- Abort if channel is not a guild channel.
- Keep logs and JSON summaries for each run.
Workflow
- Collect scope:
channel-id, optionalauthor-id,contains,regex,after,before. - Read
references/discord-limits.mdbefore deletion runs. - Run preview to estimate impact and get confirm code.
- Run deletion with confirm code.
- Share summary: scanned, matched, deleted, failed, old-vs-recent split.
Commands
Preview
node scripts/purge-preview.mjs \
--channel-id 123456789012345678 \
--author-id 987654321098765432 \
--contains "error" \
--after "2026-03-01T00:00:00Z" \
--max-scan 5000 \
--out ./tmp/purge-preview.jsonRun Purge
node scripts/purge-runner.mjs \
--channel-id 123456789012345678 \
--author-id 987654321098765432 \
--contains "error" \
--after "2026-03-01T00:00:00Z" \
--confirm "PURGE-XXXXXXXX" \
--state-file ./tmp/purge-state.json \
--out ./tmp/purge-result.jsonDry Run
node scripts/purge-runner.mjs --channel-id 123456789012345678 --confirm "PURGE-XXXXXXXX" --dry-runClone or Nuke Channel
node scripts/purge-nuke.mjs --channel-id 123456789012345678 --confirm "NUKE-XXXXXXXX" --out ./tmp/nuke.json
node scripts/purge-nuke.mjs --channel-id 123456789012345678 --confirm "NUKE-XXXXXXXX" --delete-old --out ./tmp/nuke.jsonScript Roles
scripts/purge-preview.mjs: scan channel messages, apply filters, return counts and confirm code.scripts/purge-runner.mjs: execute deletion with 2-week split (bulk-delete+ single delete fallback).scripts/purge-nuke.mjs: create replacement channel; optionally delete original channel.scripts/scan-filter.mjs: reusable scan and filtering logic.scripts/discord-api.mjs: Discord API wrapper with rate-limit retries.scripts/job-code.mjs: deterministic confirm code helpers.
Operator Rules
- Keep
max-scanbounded for broad channels. - Use
--state-fileon long jobs. - Prefer content/user/time filters over whole-channel wipes.
- Use nuke mode only when preserving channel history is unnecessary.
- Treat pinned messages as protected unless
--include-pinnedis set.
Troubleshooting
- 401/403: verify bot token and channel permissions.
- Empty preview with expected history: check
READ_MESSAGE_HISTORY. - Heavy 429: reduce parallelism and keep retry handling enabled.
bulk-deletefailures: expect messages older than 14 days, runner falls back to single deletes.- Cannot reach Discord behind a proxy: export
HTTP_PROXY/HTTPS_PROXY(uppercase recommended) and run withNODE_USE_ENV_PROXY=1, or use a recent Node that supportssetGlobalProxyFromEnv(). - If your proxy tool exposes both HTTP and SOCKS ports, point
HTTP_PROXY/HTTPS_PROXYat the HTTP port;ALL_PROXY=socks5://...alone is not enough for this skill.
Proxy Example
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NODE_USE_ENV_PROXY=1
node scripts/purge-preview.mjs --channel-id 123456789012345678 --max-scan 200