claude-code-mux

claude-code-mux

Talk to all your Claude Code agents from your phone. From a single messaging app, chat with them in their active session, switch between agents, get notified when tasks finish, and approve permissions on the go. Seamlessly pick up where you left off — start a task on your desktop, continue the conversation from your phone.

Each agent gets its own channel/thread — no switching commands needed. New agents auto-create channels; disconnected agents clean up automatically.

Supports Discord and Telegram — use one or both simultaneously.

Install

npm install -g claude-code-mux

Prerequisites

• Claude Code v2.1.80+
• Node.js 20+

Quick Start

Discord

1. Create a Discord Bot

• Go to the Discord Developer Portal → New Application → name it
• Go to Bot → Reset Token → copy the bot token
• Under Privileged Gateway Intents, enable Message Content Intent
• Go to OAuth2 → URL Generator → select scopes: bot → select permissions: Manage Channels, Send Messages, Read Message History → copy the URL and open it to invite the bot to your server

2. Get your server ID

Right-click your server name in Discord → Copy Server ID (enable Developer Mode in Settings → Advanced if you don't see this option).

3. Start the router

Create a .env file:

DISCORD_BOT_TOKEN=your-discord-bot-token
DISCORD_GUILD_ID=123456789012345678

Start the router:

claude-mux-router

Or without global install: npx claude-mux-router

Each agent gets a text channel under a "Claude Agents" category in your server.

4. Set up the bridge (once)

Register the bridge as a global MCP server so every Claude Code session picks it up:

claude mcp add -s user claude-mux-bridge -- npx claude-mux-bridge

Then add autoApprove in ~/.claude.json so the agent can reply without permission prompts:

{
  "mcpServers": {
    "claude-mux-bridge": {
      "command": "npx",
      "args": ["claude-mux-bridge"],
      "autoApprove": ["reply", "notify"]
    }
  }
}

5. Launch Claude Code sessions

Just cd into any worktree and start Claude Code:

cd ~/projects/myapp-feature-nav
claude --dangerously-load-development-channels server:claude-mux-bridge

The agent registers with the router, which creates a Discord channel for it automatically. Open the channel to chat with that agent. Spin up more sessions — each gets its own channel.

Telegram

1. Create a Telegram Bot

Message @BotFather on Telegram → /newbot → pick a name and username → copy the bot token (looks like 123456789:ABCdef...).

2. Create a Telegram group for your agents

This is the trickiest part — Telegram buries these settings, but you only do it once.

• Open Telegram → New Group → add your bot → name it (e.g. "Claude Agents")
• Open group settings → Edit → toggle Topics on
• Group settings → Administrators → Add Admin → select your bot → enable Manage Topics
• Open the #General topic and send any message (so the bot can auto-detect the group)

3. Start the router

Create a .env file:

TELEGRAM_BOT_TOKEN=123456789:ABCdef...

Start the router:

claude-mux-router

Or without global install: npx claude-mux-router

On first run, the router auto-detects your forum group and saves the chat ID to .env automatically.

4. Set up the bridge and launch sessions

Same as Discord — see steps 4 and 5 above.

Each agent gets its own topic in the Telegram forum group.

Architecture

Discord Server ────────┐
                       ├──→ Router (localhost:9900) ←──WebSocket──→ Bridge (per agent)
Telegram Forum Group ──┘         |                                     |
  (one channel/topic             |                                     |
   per agent)              Creates threads,                    MCP channel plugin
                           routes by thread,                   in Claude Code session
                           broadcasts replies

Configuration

Router

Set in .env (or as environment variables). You can use Discord, Telegram, or both — agent replies go to all connected platforms.

Discord:

Env var	Default	Description
DISCORD_BOT_TOKEN	(required)	Bot token from Developer Portal
DISCORD_GUILD_ID	(required)	Discord server ID
DISCORD_CATEGORY	Claude Agents	Category name for agent channels

Telegram:

Env var	Default	Description
TELEGRAM_BOT_TOKEN	(required)	Bot token from BotFather
TELEGRAM_CHAT_ID	auto-detect	Forum group chat ID — auto-detected, or set manually

Shared:

Env var	Default	Description
ROUTER_PORT	9900	Port the router listens on
ROUTER_HOST	127.0.0.1	Bind address — use 0.0.0.0 for remote bridges
ALLOWED_USER_IDS	(none)	Comma-separated user IDs to restrict access

Bridge

Env var	Default	Description
AGENT_NAME	auto-detect	Override agent name (default: git repo/branch)
ROUTER_PORT	9900	Must match the router's port
ROUTER_URL	ws://127.0.0.1:{ROUTER_PORT}/ws	Full WebSocket URL for remote routers

Troubleshooting

"Conflict: terminated by other getUpdates request" (Telegram) Only one process can poll a Telegram bot token at a time. If you have the official telegram@claude-plugins-official plugin, uninstall it: /plugin uninstall telegram@claude-plugins-official inside Claude Code.

"no MCP server configured with that name" Re-register with user scope: claude mcp add -s user claude-mux-bridge -- npx claude-mux-bridge

Bridge tools keep asking for permission Add autoApprove to ~/.claude.json: "autoApprove": ["reply", "notify"]

Agent name shows as directory name instead of repo/branch Make sure you cd into a git repo before starting Claude Code.

Switched to a new Telegram group? Delete TELEGRAM_CHAT_ID from .env and restart the router — it will auto-detect the new group.