claude-discord-bridge

Launch and manage Claude Code sessions on remote machines from Discord. Spin up sessions, point them at any project, and manage everything from your phone.

This is not a chat interface. Claude Code already has Channels for that. This is a remote session launcher -- start Claude Code on a headless server, Mac Mini, or any machine you can't physically sit in front of.

Why this exists

You have a Mac Mini / home server / cloud VM running 24/7. You want to:

• Start a Claude Code session on it while you're on the train
• Point it at a specific project and branch
• Send it prompts and review its work from your phone
• Run multiple sessions in parallel on different projects
• Stop sessions when done, from anywhere

This bot does that. One Discord command spawns a real Claude Code process on the target machine with full file access, tool use, and project context.

Quick Start

# 1. Clone and install
git clone https://github.com/nicolaraimondo/claude-discord-bridge.git
cd claude-discord-bridge
npm install

# 2. Configure (see "Discord Bot Setup" below for how to get these)
cp .env.example .env
# Edit .env with your bot token, app ID, guild ID, and channel ID

# 3. Register slash commands and start
npm run deploy-commands
npm start

That's it. Type /start ~/your-project in Discord.

How it works

You (phone)            Discord Bot             Remote Machine
    |                      |                        |
    |--- /start ~/myapp -->|                        |
    |<-- Thread created ---|                        |
    |                      |                        |
    |--- "add auth" ------>|--- claude -p "..." --->|
    |                      |    (spawns process)    |
    |                      |<-- response -----------|
    |<-- Response posted --|                        |
    |                      |                        |
    |--- "use OAuth" ----->|--- claude -p --resume->|
    |                      |    (resumes session)   |
    |<-- Response posted --|                        |
    |                      |                        |
    |--- /status --------->|   "2 sessions active"  |
    |--- /stop my-feature->|--- kills session ----->|

Each message spawns claude -p "your message" --session-id UUID. The --resume flag maintains full conversation context across messages. No persistent processes between messages, no databases.

What this is NOT

This project	Not this
Launches Claude Code on remote machines	A chat wrapper around the API
Manages session lifecycle (start/stop/status)	Claude Code Channels (which connects to existing sessions)
Runs real CLI processes with full file/tool access	A hosted service -- your code never leaves your machine

Commands

Command	Description
/start ~/my-project	Launch a session in a project directory
/start ~/my-project --name my-feature	Launch with a custom session name
/stop my-feature	End a session and archive the thread
/status	Show all active sessions

After /start, a thread is created. Type naturally in the thread. Claude has full access to the project -- it can read files, run commands, make edits, commit code. Conversations carry across messages.

Features

• Remote session launching -- spawn Claude Code on any machine from Discord
• Multi-session management -- run multiple sessions on different projects simultaneously
• Multi-turn context -- --resume flag maintains full conversation history
• Message queuing -- if Claude is busy, messages queue and process in order
• Secret redaction -- API keys, tokens, and credentials are automatically stripped from responses
• Rate limiting -- 10 messages per minute per user to prevent abuse
• 5-minute timeout -- long-running prompts are killed after 5 minutes

Use cases

• Headless dev server -- run Claude Code on a Mac Mini or home server, control it from anywhere
• Cloud VM -- launch sessions on a GPU instance or build server from your phone
• Team bot -- shared Discord server where team members can spin up sessions on a shared dev machine
• CI/CD companion -- start a session to investigate a failing build while you're away from your desk

Discord Bot Setup

1. Go to Discord Developer Portal
2. Click New Application, give it a name
3. Go to Bot tab, click Reset Token, copy the token
4. Enable Privileged Gateway Intents: Message Content Intent
5. Go to OAuth2 > URL Generator:
   • Scopes: bot, applications.commands
   • Bot Permissions: Send Messages, Create Public Threads, Send Messages in Threads, Add Reactions, Manage Threads
6. Open the generated URL to invite the bot to your server
7. Get your IDs: enable Developer Mode in Discord (Settings > Advanced), then right-click server/channel > Copy ID

Requirements

• Node.js 20+
• Claude Code CLI installed and authenticated (claude in PATH)
• A Discord server you admin

Security

User allowlist (required): Only Discord users listed in ALLOWED_DISCORD_USER_IDS can use the bot. If this env var is not set, the bot denies all requests (fail closed). This prevents unauthorized users from spawning sessions on your machine.

Directory allowlist (recommended): Set ALLOWED_PROJECT_DIRS to restrict which directories /start can access. Without this, any allowed user can point Claude at any directory on the host.

Secret redaction: Claude responses pass through a filter that catches API keys (OpenAI, Anthropic, AWS, GitHub, Stripe, Slack, Vercel, npm), JWT/Bearer tokens, database connection strings, SSH private keys, GCP service account keys, and env var assignments. ANSI escape sequences are stripped before pattern matching.

Rate limiting: 10 messages per minute per user, 5 commands per minute, max 10 messages queued per session, max 5 concurrent sessions.

Important: This bot runs claude --dangerously-skip-permissions by default. Set SKIP_PERMISSIONS=false in .env to disable this. Only run the bot on machines you trust.

Architecture

~640 lines of JavaScript. Four files:

File	What it does
lib/session-spawner.js	Spawns claude -p per message with --resume
lib/session-store.js	In-memory session tracking (no database)
lib/thread-handler.js	Forwards Discord messages, queues, posts responses
lib/redact-filter.js	Strips secrets from output before Discord

Running as a background service

macOS (launchd)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.claude-discord-bridge</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/node</string>
    <string>/path/to/claude-discord-bridge/index.js</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/path/to/claude-discord-bridge</string>
  <key>KeepAlive</key>
  <true/>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
  </dict>
</dict>
</plist>

Save to ~/Library/LaunchAgents/com.claude-discord-bridge.plist, then:

launchctl load ~/Library/LaunchAgents/com.claude-discord-bridge.plist

Linux (systemd)

[Unit]
Description=Claude Discord Bridge
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/claude-discord-bridge
ExecStart=/usr/bin/node index.js
Restart=always
EnvironmentFile=/path/to/claude-discord-bridge/.env

[Install]
WantedBy=multi-user.target

Contributing

Contributions welcome. If you use this, I'd love to hear about your setup -- open an issue or ping me on X.

License

MIT

---

Built by Nicola Raimondo at OpenScouter -- AI-powered accessibility testing.