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