/guides/discord-bot

Discord bot

Deploy free-claude-code as a Discord bot. Remote autonomous coding with tree-based threading and live progress streaming.

Discord bot

Control Claude Code remotely from Discord. Send coding tasks, watch live progress, and manage multiple concurrent sessions from anywhere.

Features

• Tree-based threading: Reply to any message to fork the conversation
• Session persistence: Conversations survive server restarts
• Live streaming: See thinking tokens, tool calls, and results in real time
• Unlimited sessions: Concurrency controlled by PROVIDER_MAX_CONCURRENCY
• Voice notes: Send voice messages; transcribed and processed as prompts
• Commands: /stop, /clear, /stats for session management

Prerequisites

You need:

1. A Discord account
2. Permission to create bots (any Discord account has this)
3. free-claude-code installed and running

Step 1: Create a Discord bot

1. Go to Discord Developer Portal
2. Click “New Application” and name it (e.g., “Claude Code Bot”)
3. Navigate to “Bot” in the left sidebar
4. Click “Add Bot” and confirm
5. Under “Privileged Gateway Intents”, enable:
   • Message Content Intent (required to read messages)
6. Click “Reset Token” and copy the new token

Step 2: Invite the bot to your server

1. In the Developer Portal, go to “OAuth2” → “URL Generator”
2. Select scopes:
   • bot
3. Select bot permissions:
   • Read Messages/View Channels
   • Send Messages
   • Manage Messages
   • Read Message History
4. Copy the generated URL and open it in your browser
5. Select the server to add the bot to

Step 3: Get channel IDs

Enable Developer Mode in Discord:

1. Discord Settings → Advanced → Enable Developer Mode

Get your channel IDs:

1. Right-click the channel where the bot should operate
2. Click “Copy Channel ID”
3. Save this ID

Repeat for multiple channels if needed.

Step 4: Configure free-claude-code

Edit .env:

MESSAGING_PLATFORM="discord"
DISCORD_BOT_TOKEN="your_discord_bot_token_here"
ALLOWED_DISCORD_CHANNELS="123456789,987654321"

Replace the channel IDs with your copied values. Comma-separate multiple channels.

Configure the workspace where Claude will operate:

CLAUDE_WORKSPACE="./agent_workspace"
ALLOWED_DIR="C:/Users/yourname/projects"

CLAUDE_WORKSPACE is where the bot clones repos and writes files. ALLOWED_DIR restricts which directories Claude can access.

Step 5: Start the server

uv run uvicorn server:app --host 0.0.0.0 --port 8082

The bot will connect to Discord and appear online in your server.

Using the bot

Basic usage

Send a message in an allowed channel:

Write a Python script that downloads the front page of Hacker News and extracts all article titles

The bot will:

1. Acknowledge the request
2. Stream thinking tokens (if enabled)
3. Execute tool calls (file reads, edits, bash commands)
4. Return the final result

Threading

Reply to any bot message to continue that conversation branch:

> [Your original request]
  ↳ [Bot response]
    ↳ [Your reply: "Now make it save to a JSON file"]

This creates a tree structure. You can have multiple parallel conversations with the same bot in different threads.

Commands

Voice notes

Send a voice message in Discord. The bot will:

1. Download the audio
2. Transcribe using configured Whisper backend
3. Process the transcribed text as a normal prompt

Configure voice transcription:

VOICE_NOTE_ENABLED=true
WHISPER_DEVICE="cpu"        # Options: cpu, cuda, nvidia_nim
WHISPER_MODEL="base"        # Options: tiny, base, small, medium, large-v2, large-v3, large-v3-turbo

For NVIDIA NIM voice transcription:

WHISPER_DEVICE="nvidia_nim"
WHISPER_MODEL="openai/whisper-large-v3"
NVIDIA_NIM_API_KEY="nvapi-your-key"

Install voice extras:

uv sync --extra voice_local     # Local Whisper
uv sync --extra voice           # NVIDIA NIM voice

Session management

Sessions persist across server restarts. The bot stores conversation state in CLAUDE_WORKSPACE.

To clear all sessions:

/clear

To stop a running task:

/stop

Rate limiting

Configure Discord-specific rate limits:

MESSAGING_RATE_LIMIT=1
MESSAGING_RATE_WINDOW=1

This prevents the bot from sending more than 1 message per second, avoiding Discord rate limits.

Security

• Restrict channels: Use ALLOWED_DISCORD_CHANNELS to limit where the bot operates
• Set allowed directories: ALLOWED_DIR prevents Claude from accessing files outside your workspace
• Use authentication: Set ANTHROPIC_AUTH_TOKEN to require authentication for proxy access

Troubleshooting

Bot shows offline: Check the token is correct. Reset the token if needed.

Bot doesn’t respond: Verify MESSAGING_PLATFORM="discord" is set. Check logs for connection errors.

“Channel not allowed” errors: Add the channel ID to ALLOWED_DISCORD_CHANNELS.

Voice notes not working: Verify voice extras are installed and VOICE_NOTE_ENABLED=true.

Sessions lost on restart: Ensure CLAUDE_WORKSPACE is a persistent directory, not a temp folder.