claude-code-mux

claude-mux

One messaging client, many Claude Code agents. A multiplexer that routes messages between a messaging platform (Telegram, Discord, etc.) and multiple Claude Code sessions running on different worktrees.

Architecture

Telegram Bot
    |
    v
Router (standalone process, localhost:9900)
  - Owns the bot token
  - Handles /list, /switch, /status commands
  - Fuzzy-matches agent names on /switch
  - Natural language switching via LLM (Anthropic, OpenAI, or Google)
  - Routes messages to the active agent
    |  (WebSocket)
    v
Bridge (MCP channel plugin, one per Claude Code session)
  - Auto-detects agent name from git (repo/branch)
  - Registers with router on startup
  - Pushes messages into Claude Code session
  - Sends replies + notifications back through router

Install

npm install -g claude-mux

Prerequisites

• Claude Code v2.1.80+
• Node.js 20+
• A Telegram bot token (see Create a Telegram Bot below)

Create a Telegram Bot

• Message @BotFather on Telegram → /newbot → pick a name and username
• Copy the bot token (looks like 123456789:ABCdef...)
• Keep the token secret — never commit it to git

Setup Router

The router is a standalone process that owns the Telegram bot and runs once on your machine (or a server). All agents connect to it.

1. Configure environment

Create a .env file (the router loads it automatically):

# Required — your bot token from BotFather
TELEGRAM_BOT_TOKEN=123456789:ABCdef...

# Optional — enables LLM-powered natural language switching
# Pick a provider and set the corresponding API key:
ROUTER_MODEL=anthropic:claude-haiku-4-5-20251001
ANTHROPIC_API_KEY=sk-ant-...

# Or use OpenAI:
# ROUTER_MODEL=openai:gpt-5.4-nano
# OPENAI_API_KEY=sk-...

# Or Google:
# ROUTER_MODEL=google:gemini-3.1-flash-lite-preview
# GOOGLE_GENERATIVE_AI_API_KEY=...

See Configuration > Router for all available options.

2. Start the router

claude-mux-router

Or without global install:

npx claude-mux-router

The router loads .env automatically and starts listening on ws://127.0.0.1:9900/ws.

3. Pair your Telegram account

Send any message to your bot in Telegram. The router auto-pairs with the first sender and remembers the chat ID for all future replies. If you set ALLOWED_USER_IDS in .env, only those users can interact with the bot.

Setup Agent

Each Claude Code session needs the bridge MCP plugin to connect to the router. You register it once globally, then every agent picks it up automatically.

1. Register the bridge as a global MCP server

Use claude mcp add with the -s user flag so the bridge is available in all Claude Code sessions:

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

2. Enable autoApprove for bridge tools

Without this, you'd get a permission prompt every time the agent tries to reply or send a notification — which defeats the purpose of async communication. Open ~/.claude.json and add autoApprove to the bridge entry:

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

3. Launch Claude Code sessions

Just cd into any worktree and start Claude Code. The agent name is auto-detected from git (repo/branch), or falls back to the directory name:

# Terminal 1 — auto-detects as "myapp/feature-nav"
cd ~/projects/myapp-feature-nav
claude --dangerously-load-development-channels server:claude-mux-bridge

# Terminal 2 — auto-detects as "monots/encore"
cd ~/worktrees/monots-encore
claude --dangerously-load-development-channels server:claude-mux-bridge

# Terminal 3 — auto-detects as "myapp/fix-auth-bug"
cd ~/projects/myapp-fix-auth-bug
claude --dangerously-load-development-channels server:claude-mux-bridge

No per-session env vars needed. Each session registers with the router automatically. When you spin up a new worktree, just start Claude Code in it — no extra setup required.

Usage (from Telegram)

Commands

Command	Description
/list	Show all connected agents
/switch <agent>	Switch to an agent by repo, branch, directory, or description
/status	Show which agent is active
/help	Show all commands

Smart switching

You don't need to type the exact agent name. The router first tries token-based fuzzy matching (instant, no API call). If that's ambiguous, and you've configured a ROUTER_MODEL, it falls back to the LLM to interpret natural language:

You: /list
Bot: Connected agents:
       monots/encore (active) — up 32m
       myapp/feature-nav — up 15m
       myapp/fix-auth-bug — up 5m

You: /switch monots encore
Bot: Switched to monots/encore

You: /switch nav
Bot: Switched to myapp/feature-nav

You: /switch myapp
Bot: Multiple matches for "myapp":
       1. myapp/feature-nav
       2. myapp/fix-auth-bug
     Be more specific, or use /switch with the full name.

You: /switch fix auth
Bot: Switched to myapp/fix-auth-bug

You: switch to the one working on the bug fix
Bot: Switched to myapp/fix-auth-bug

The last example doesn't use a / command at all. Any message containing the word "switch" triggers the LLM to classify whether it's a switch intent or a regular message to the agent. This means "switch to the one working on the bug fix" gets intercepted and resolved by the LLM, while "can you switch the database driver to postgres" passes through to the agent as a normal message. Without a ROUTER_MODEL configured, only /switch commands with fuzzy matching are available.

Chatting with agents

Any non-command message goes to the active agent. If only one agent is connected, it's auto-selected.

You: can you add pagination to the /users endpoint?
Bot: [monots/encore] I'll add pagination to the /users endpoint...

Notifications

Agents proactively notify you when tasks complete:

Bot: [myapp/feature-nav] Finished refactoring the nav component.
     Changed 3 files, all 24 tests passing.
     Ready for your review.

Permission relay

When an agent needs permission to run a tool, you'll get a prompt:

Bot: [monots/encore] Permission request:
     Tool: Bash
     Action: Run npm test
     Reply "yes abcde" or "no abcde"

You: yes abcde

Dynamic worktrees

The whole point of this tool: you don't create new bots or set env vars when you spin up a new worktree. Just start Claude Code in the directory:

cd ~/worktrees/myapp-hotfix-123
claude --dangerously-load-development-channels server:claude-mux-bridge

The bridge detects myapp/hotfix-123 from git and registers automatically. When you close the session, it deregisters and your Telegram shows a disconnect notification.

Configuration

Router

Set these in .env (or as environment variables) where you run pnpm router:

Env var	Default	Description
TELEGRAM_BOT_TOKEN	(required)	Bot token from BotFather
ROUTER_MODEL	(optional)	LLM for smart switching, format provider:model-id (e.g. anthropic:claude-haiku-4-5-20251001, openai:gpt-5.4-nano, google:gemini-3.1-flash-lite-preview)
ANTHROPIC_API_KEY	(optional)	API key for Anthropic models. If set without ROUTER_MODEL, defaults to anthropic:claude-haiku-4-5-20251001
OPENAI_API_KEY	(optional)	API key for OpenAI models
GOOGLE_GENERATIVE_AI_API_KEY	(optional)	API key for Google models
ROUTER_PORT	9900	Port the router listens on
ROUTER_HOST	127.0.0.1	Bind address — use 0.0.0.0 to allow remote bridge connections
ALLOWED_USER_IDS	auto-pair	Comma-separated Telegram user IDs

Bridge

The agent name is detected automatically: git repo + branch (e.g. myapp/feature-nav), or the current directory name if not in a git repo. Most bridge env vars are optional — the defaults work when router and bridge run on the same machine.

Env var	Default	Description
AGENT_NAME	auto-detect	Override the agent name (default: git repo/branch, or directory name)
ROUTER_PORT	9900	Must match the router's ROUTER_PORT
ROUTER_URL	ws://127.0.0.1:{ROUTER_PORT}/ws	Full WebSocket URL — set this when the router is on a different machine

Troubleshooting

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

"no MCP server configured with that name" The bridge was likely registered to a project scope instead of user scope. Re-register with the -s user flag:

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

Bridge tools keep asking for permission Add autoApprove to the MCP server config in ~/.claude.json:

"autoApprove": ["reply", "notify"]

Agent name shows as the directory name instead of repo/branch The bridge couldn't detect git info. Make sure you cd into a git repo before starting Claude Code. If there's no git remote, it uses the repo root directory + branch. If it's not a git repo at all, it falls back to the current directory name.