discord-agent-bridge

🌐 한국어 | English

Self-hosted Discord bot that runs AI coding agents — Claude Code, Codex, and more — per channel. Role-based access, multi-server, extensible.

A self-hosted Discord bot that puts Claude Code (or Codex) into a Discord channel, running on your own machine. Published on npm — one npm install -g and three commands to auto-start.

Why this?

• 🏠 Fully self-hosted. The bot runs on your PC. Your code, your sessions, and your CLI tokens never leave your machine.
• 📱 You don't need to be at your desk. Fire off a task from Discord on your phone — streaming output, tool-run logs, and permission prompts all show up in the channel.
• 🗂️ One channel = one project = one session. Each channel is bound to its own folder, backend, model, and permission mode. Isolated by design.
• 👥 Team-friendly by default. Anyone in the channel can watch the session unfold. A 3-tier role system (admin / execute / read-only) controls who can actually run things.
• 🔀 Claude ⇄ Codex on the fly. Switch backends with a single /mode command.
• ⚙️ Same power as the terminal. Reads your project's .claude/ and .codex/ configs as-is — subagents, skills, hooks, MCP, and plugin commands all work exactly like they do in the CLI.

Prerequisites

• Node.js 20 or later
• The CLI for whichever backend you'll use, already installed and logged in:
  • Claude mode → Claude Code (claude login, or ANTHROPIC_API_KEY)
  • Codex mode → the codex CLI, logged in
• A Discord bot token (Step 1 below)

Step 1 — Create a Discord bot

You need your own bot. About 5 minutes.

1. Open the Discord Developer Portal → top-right New Application → give it a name (e.g. my-agent-bot) → Create.
2. Left sidebar Bot tab → Reset Token → copy the token and stash it somewhere safe.
   • ⚠️ This token is a password. If it leaks, hit Reset Token immediately.
3. Still on the Bot tab, under Privileged Gateway Intents:
   • ✅ MESSAGE CONTENT INTENT — required (the bot has to read message content)
   • ✅ SERVER MEMBERS INTENT — recommended (used for role checks)
   • Enable and Save Changes.
4. Left sidebar OAuth2 tab → copy the Client ID (Application ID).
5. Build an invite link — OAuth2 → URL Generator:
   • Scopes: bot, applications.commands
   • Bot Permissions: Manage Channels, Send Messages, Embed Links, Attach Files, Read Message History, Create Public Threads, Send Messages in Threads, Manage Threads, Add Reactions
   • Paste the generated URL into your browser and invite it to your server.

Step 2 — Install & run

Three lines take you from install to auto-start on reboot. service install picks the right auto-start for your OS — launchd on macOS, systemd on Linux, Task Scheduler on Windows.

npm install -g discord-agent-bridge      # install
discord-agent-bridge --setup             # first run only (enter token, etc.)
discord-agent-bridge service install     # register auto-start + start now

Manage it:

discord-agent-bridge service status      # is it registered / running?
discord-agent-bridge service restart     # restart
discord-agent-bridge service uninstall   # remove

Upgrade:

npm install -g discord-agent-bridge@latest
discord-agent-bridge service restart

⚠️ Windows note: registers a Task Scheduler logon trigger, so the bot starts at login (no admin needed). It doesn't guarantee auto-restart on crash (macOS/Linux do).

Step 3 — Using it in Discord

Once the bot joins a server, it automatically creates a control channel (#session-generator), a sessions category, and a notifications channel (#agent-status) (as long as it has Manage Channels). From there: /config → /agent start.

1. (Automatic) Channel structure is created on bot start / server invite. Admins can rebuild it manually with /init (existing channels are reused).
2. /config (admin) — set role tiers and defaults. Server Administrators can always use the bot even before roles are configured.
3. In #session-generator, run /agent start. The wizard walks you through: working folder → backend (Claude / Codex) → model → reasoning effort → permission mode. Each step advances with a Next button. The folder browser lets you navigate to parents/other volumes, create folders, and resume prior sessions. On confirm, a dedicated session channel (proj-<folder>) is created and bound.
4. In that session channel, just send normal messages. Claude mode gives you streaming output, tool-run threads, and permission approval buttons.

Key commands

| Command | Description | |---|---| | /init | (admin) Create the control channel + sessions category (reuses existing) | | /agent start | Start a new session — creates a dedicated session channel on confirm | | /agent resume | Resume a previous session | | /agent close | End the session and delete its channel | | /agent stats | Active sessions, session stats, and Claude usage (only you can see it) | | /mode <claude\|codex> | Switch backend (⚠️ starts a fresh conversation — prior context is not carried over) | | /mode perm <mode\|profile> | Switch permission mode/profile (session context is preserved) | | /stop | Stop the current session immediately (kill switch) | | /stop-all | (admin) Stop every session | | /config | (admin) Configure role tiers + defaults (backend, model, permission mode, language, Codex path) |

Permission modes

• default — asks before each tool run with Allow/Deny buttons (safest)
• acceptEdits — file edits auto-accepted
• plan — plans only, no execution
• bypassPermissions — fully automatic (trusted projects only)

Codex maps these onto its own approval/sandbox modes.

Event notifications (#agent-status)

Completions and errors from all your sessions get summarized into a single #agent-status channel. Toggle it and change the target channel from /config → 🔔 Notification Settings.

License: MIT