discord

multi-channel-discord

Project-aware Discord bot for Claude Code. One Discord bot, many isolated channels, each with its own system prompt, conversation history, and (eventually) git working tree + PR workflow.

Status: work in progress. Phases 1–3c are merged on main and pass typecheck + all in-tree smoke tests. End-to-end with a live Claude subprocess has not been verified yet — see Status.

Forked from anthropics/claude-plugins-official/external_plugins/discord (Apache-2.0). Backwards-compatible with the upstream behavior when no channels.json is present.

📖 For runtime architecture, debugging notes, and the master CLAUDE.md template, read ARCHITECTURE.md.

What it adds vs upstream

	upstream	this fork
Message routing	one Claude session for all messages	per-channel Claude subprocess (lazy spawn, idle eviction, cap)
System prompt	global (CLAUDE.md in cwd)	per channel (projects/<slug>/CLAUDE.md)
History	global	per channel (Claude session resume per-project)
Provisioning	manual config	!project create/clone/... from a master Discord channel + /discord:project skill
Git/PR (planned)	—	clone existing repo, branch-and-PR commits via GitHub Octokit / Azure DevOps REST
Auth model	uses Claude subscription via Claude Code CLI	same — subscription only, never API key

How it works

Discord (one bot) ─→ server.ts ─→ ProjectPool ─→ N × claude subprocesses
                          │              │              │
                          │              │              └── HTTP MCP →─┐
                          │              │                              │
                          │              ├── Map<chat_id, process>      │
                          │              └── lazy spawn / idle evict    │
                          │                                              │
                          └── MasterMcpServer ←─────────────────────────┘
                                  └── one in-process http.Server, multiplexed by URL path
                                      `/mcp/<chat_id>`

• Each project channel ⇒ one claude subprocess running in projects/<slug>/.
• The subprocess is given an --mcp-config pointing at http://127.0.0.1:<port>/mcp/<chat_id> so its tool calls (currently reply) are bound to the right Discord channel.
• Inbound Discord messages reach Claude as notifications/claude/channel MCP notifications, scoped to the channel's MCP session.
• Outbound replies stream from Claude → master MCP server → pool → Discord, chunked at the upstream 2000-char limit.

Cross-platform: HTTP-on-localhost works identically on Linux, macOS, and Windows. No Unix sockets, no named pipes.

Status

Phases merged:

Phase	What	Tests
1	channels.json registry, /discord:project init skill, file layout	smoke ✓
2	Master-channel command parser (!project list/show/help)	20/20 ✓
3a	ProjectPool lifecycle on a Mock backend	18/18 ✓
3b	HTTP MCP server (just reply tool) + ClaudeProjectProcess wrapper	7/7 ✓
3c	Pool wired into server.ts; chunked Discord reply dispatch; clean shutdown	typecheck ✓

Not yet:

• Phase 4: mutation verbs (!project create, clone, set, rm) — still stubbed
• Phase 5: git layer (clone/init), credential helper, branch/PR workflow
• Phase 6: cross-platform deploy (macOS launchd, Windows service)
• Tools other than reply on the master MCP server (react, edit_message, download_attachment, fetch_messages)

Live smoke against a real claude CLI: not yet performed. The single-session passthrough is identical to upstream when channels.json doesn't exist, so the fork is safe to run in single-session mode while phase 3c stabilizes.

Side-by-side install (recommended for first time)

Most operators are already running the upstream claude-channel-discord bot. To trial this fork without taking the existing bot offline, register a second Discord application with its own bot token and run the new bot in a separate state directory.

git clone https://github.com/chan4lk/claude-multi-channel-discord ~/dev/multi-channel-discord
cd ~/dev/multi-channel-discord
bun install

Then in the Discord Developer Portal: