Discord Purge Bot

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...

Run controlled cleanup in Discord guild channels with safety gates and audit-friendly outputs.

Safety Contract

• Use only a bot token (DISCORD_BOT_TOKEN or --token).
• Refuse user-account token flows and self-bot behavior.
• Run purge-preview.mjs first 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

1. Collect scope: channel-id, optional author-id, contains, regex, after, before.
2. Read references/discord-limits.md before deletion runs.
3. Run preview to estimate impact and get confirm code.
4. Run deletion with confirm code.
5. 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.json

Run 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.json

Dry Run

node scripts/purge-runner.mjs --channel-id 123456789012345678 --confirm "PURGE-XXXXXXXX" --dry-run

Clone 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.json

Script 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-scan bounded for broad channels.
• Use --state-file on 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-pinned is 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-delete failures: 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 with NODE_USE_ENV_PROXY=1, or use a recent Node that supports setGlobalProxyFromEnv().
• If your proxy tool exposes both HTTP and SOCKS ports, point HTTP_PROXY/HTTPS_PROXY at 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