Discord Bot Setup

Discord Bot Setup

Prerequisites

Collect from user via AskUserQuestion:

1. Bot Token — from Discord Developer Portal
2. Discord User ID — for whitelist (Developer Mode > right-click avatar > Copy User ID)
3. Auto-respond Channel ID — (optional) channel where bot responds without @mention
4. STT engine — gemini (recommended) / chirp2 / whisper:medium (default: gemini)
5. GCP Project — for Gemini/Chirp2 STT (default: use gcloud config)

If no Bot Token, guide user through Discord Developer Portal setup:

• Create Application > Bot > Reset Token > enable all 3 Intents (Presence, Server Members, Message Content)
• OAuth2 > Scopes: bot, applications.commands > Permissions: Send Messages, Read Message History, Embed Links, Attach Files, View Channels
• Disable User Install in Installation settings (security)

Installation

pip install py-cord --break-system-packages
sudo apt-get install -y ffmpeg jq
pip install google-genai --break-system-packages   # Gemini STT (recommended)
pip install openai-whisper --break-system-packages  # Whisper fallback

Deploy Bot

1. Read scripts/bot_template.py — this is the complete, production-ready bot script
2. Copy to ~/.claude/discord-bot/bot.py
3. Create ~/.claude/discord-bot/.env with config:

   DISCORD_BOT_TOKEN=<bot_token>
   ALLOWED_USER_IDS=<user_discord_id>
   AUTO_RESPOND_CHANNELS=<channel_id>
   STT_ENGINE=gemini
   GOOGLE_CLOUD_PROJECT=<gcp_project>
   CHIRP2_LOCATION=us-central1
   

4. Copy scripts/send-to-discord.sh to ~/.claude/scripts/send-to-discord.sh and set BOT_TOKEN/CHANNEL_ID
5. chmod +x ~/.claude/scripts/send-to-discord.sh

STT Engine Configuration

Three engines available, configured via STT_ENGINE in .env:

• gemini (recommended) — Uses Gemini multimodal LLM for transcription. Understands semantics, corrects homophones, handles tech terms. Requires google-genai SDK and GCP project with Vertex AI API enabled.
  • Current best: gemini-3-flash-preview with thinking_level=MINIMAL (~3.4s, excellent quality)
  • Alternative: gemini-2.0-flash (~3s, excellent quality, more regions)
  • Budget option: gemini-2.5-flash-lite (~2.1s, good quality)
• chirp2 — Google Cloud Speech-to-Text V2 (Chirp 2). Pure ASR, no semantic understanding. Poor with homophones.
• whisper:medium — Local OpenAI Whisper. No network dependency, ~2-3s, ok quality.

Fallback chain: Gemini → Chirp 2 → Whisper (automatic on failure)

Important: Gemini 3 Flash Preview only available in global region. Other Gemini models work in us-central1.

Start Bot

mkdir -p ~/.claude/discord-bot
# Copy wrapper script
cp scripts/run.sh ~/.claude/discord-bot/run.sh
chmod +x ~/.claude/discord-bot/run.sh
# Start in tmux (survives shell disconnect, wrapper auto-restarts on /restart)
tmux new-session -d -s discord-bot 'bash ~/.claude/discord-bot/run.sh'

Verify: tmux ls and tail -5 ~/.claude/discord-bot/bot.log

Critical: Only one bot process must run. Multiple processes = duplicate messages.

Memory Setup

For auto memory to work across sessions:

1. Ensure ~/.claude/CLAUDE.md exists with global preferences
2. Create ~/.claude/projects/-home-<user>/memory/MEMORY.md as memory index
3. Bot already passes CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 to Claude subprocess

Slash Commands

Key Features

• Persistent Claude process per user via socket.socketpair() — full interactive mode
• Session history — /end archives, /sessions shows dropdown to switch back
• Gemini STT — multimodal voice transcription with semantic understanding (understands context, corrects homophones)
• STT fallback chain — Gemini → Chirp 2 → Whisper (auto-fallback on failure)
• Smart message splitting — split at newlines for Discord's 2000 char limit
• Process auto-restart — if Claude dies, recreate transparently on next message
• Graceful restart — /restart command triggers exit code 42, wrapper script auto-restarts
• FD isolation — subprocess.Popen(close_fds=True) prevents Claude from inheriting Discord websocket FD
• Safety prompt — system prompt forbids Claude subprocess from killing/restarting bot process

References

• Architecture details: See references/architecture.md for socketpair protocol, message format, session management internals, and security model
• Troubleshooting: See references/troubleshooting.md for common issues and fixes

Files Created

~/.claude/discord-bot/
├── bot.py           # Main bot script
├── run.sh           # Wrapper script (auto-restart on exit code 42)
├── bot.log          # Runtime logs (tail -f)
└── sessions.json    # Per-user session mapping (auto-created)

~/.claude/scripts/
└── send-to-discord.sh  # Claude Code → Discord messaging