claude-code-mux 0.1.0

package/README.md

@@ -0,0 +1,271 @@
+# 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.
+
+<img src="demo.png" width="400" alt="claude-mux demo — Telegram chat showing /list, /status, /help commands and agent switching" />
+
+## 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
+
+```bash
+npm install -g claude-mux
+```
+
+## Prerequisites
+
+- Claude Code v2.1.80+
+- Node.js 20+
+- A Telegram bot token (see [Create a Telegram Bot](#create-a-telegram-bot) below)
+
+## Create a Telegram Bot
+
+1. Message **@BotFather** on Telegram → `/newbot` → pick a name and username
+2. Copy the **bot token** (looks like `123456789:ABCdef...`)
+3. 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):
+
+```env
+# 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](#router) for all available options.
+
+### 2. Start the router
+
+```bash
+claude-mux-router
+```
+
+Or without global install:
+
+```bash
+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:
+
+```bash
+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:
+
+```json
+{
+  "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:
+
+```bash
+# 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:
+
+```bash
+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:
+```bash
+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`:
+```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.

package/dist/bridge.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * claude-mux bridge
+ *
+ * MCP channel plugin that runs inside a Claude Code session.
+ * Connects to the router via WebSocket and bridges messages
+ * between Telegram (via router) and the Claude Code session.
+ *
+ * Agent name is auto-detected from git (repo/branch), or can be
+ * overridden with the AGENT_NAME env var.
+ *
+ * Usage:
+ *   claude --dangerously-load-development-channels server:claude-mux-bridge
+ *
+ * Agent name is detected automatically:
+ *   1. git remote repo name + current branch (e.g. "myapp/feature-nav")
+ *   2. git repo root directory + branch (if no remote)
+ *   3. current directory name (if not a git repo)
+ *
+ * Optional env vars:
+ *   ROUTER_PORT   — port to connect to (default: 9900, shared with router)
+ *   ROUTER_URL    — full WebSocket URL, overrides ROUTER_PORT (default: ws://127.0.0.1:{ROUTER_PORT}/ws)
+ */
+export {};

package/dist/bridge.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * claude-mux bridge
+ *
+ * MCP channel plugin that runs inside a Claude Code session.
+ * Connects to the router via WebSocket and bridges messages
+ * between Telegram (via router) and the Claude Code session.
+ *
+ * Agent name is auto-detected from git (repo/branch), or can be
+ * overridden with the AGENT_NAME env var.
+ *
+ * Usage:
+ *   claude --dangerously-load-development-channels server:claude-mux-bridge
+ *
+ * Agent name is detected automatically:
+ *   1. git remote repo name + current branch (e.g. "myapp/feature-nav")
+ *   2. git repo root directory + branch (if no remote)
+ *   3. current directory name (if not a git repo)
+ *
+ * Optional env vars:
+ *   ROUTER_PORT   — port to connect to (default: 9900, shared with router)
+ *   ROUTER_URL    — full WebSocket URL, overrides ROUTER_PORT (default: ws://127.0.0.1:{ROUTER_PORT}/ws)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { execSync } from 'child_process';
+import { WebSocket } from 'ws';
+// ---------- git detection ----------
+function detectAgentName() {
+    try {
+        // get the repo name from the remote origin, or fall back to directory name
+        let repoName;
+        try {
+            const remoteUrl = execSync('git remote get-url origin', { encoding: 'utf-8' }).trim();
+            // extract repo name from URLs like:
+            //   git@github.com:user/repo.git
+            //   https://github.com/user/repo.git
+            repoName = remoteUrl.split('/').pop()?.replace(/\.git$/, '') ?? '';
+        }
+        catch {
+            // no remote — use the repo root directory name
+            const topLevel = execSync('git rev-parse --show-toplevel', { encoding: 'utf-8' }).trim();
+            repoName = topLevel.split('/').pop() ?? '';
+        }
+        // get the current branch
+        const branch = execSync('git branch --show-current', { encoding: 'utf-8' }).trim();
+        if (repoName && branch) {
+            return `${repoName}/${branch}`;
+        }
+        if (repoName) {
+            return repoName;
+        }
+    }
+    catch {
+        // not in a git repo
+    }
+    // last resort: use the current directory name
+    const cwd = process.cwd();
+    return cwd.split('/').pop() ?? 'unknown';
+}
+// ---------- config ----------
+const AGENT_NAME = process.env.AGENT_NAME ?? detectAgentName();
+console.error(`[bridge] Agent name: ${AGENT_NAME}`);
+const ROUTER_PORT = process.env.ROUTER_PORT ?? '9900';
+const ROUTER_URL = process.env.ROUTER_URL ?? `ws://127.0.0.1:${ROUTER_PORT}/ws`;
+// ---------- MCP server ----------
+const mcp = new McpServer({ name: `claude-mux-bridge-${AGENT_NAME}`, version: '0.1.0' }, {
+    capabilities: {
+        experimental: {
+            'claude/channel': {},
+            'claude/channel/permission': {},
+        },
+    },
+    instructions: [
+        `Messages arrive as <channel source="claude-mux-bridge-${AGENT_NAME}" sender="..." chat_id="...">. `,
+        'Reply using the "reply" tool, passing the chat_id from the tag. ',
+        'When you finish a task, ALWAYS send a completion summary via the "notify" tool so the user gets a notification. ',
+        `You are agent "${AGENT_NAME}". If asked who you are or which agent this is, identify yourself by this name.`,
+    ].join(''),
+});
+// ---------- tools ----------
+mcp.registerTool('reply', {
+    description: 'Reply to a message. Use this when responding to a user message that arrived via the channel.',
+    inputSchema: {
+        chat_id: z.string().describe('The chat_id from the inbound <channel> tag'),
+        text: z.string().describe('The reply text to send'),
+    },
+}, async ({ text }) => {
+    sendToRouter({ type: 'reply', text });
+    return { content: [{ type: 'text', text: 'sent' }] };
+});
+mcp.registerTool('notify', {
+    description: 'Send a proactive notification to the user. Use this when a task completes, an error occurs, or you need to alert the user about something without them asking.',
+    inputSchema: {
+        text: z.string().describe('The notification text to send'),
+    },
+}, async ({ text }) => {
+    sendToRouter({ type: 'notify', text });
+    return { content: [{ type: 'text', text: 'notification sent' }] };
+});
+// ---------- permission relay ----------
+const PermissionRequestSchema = z.object({
+    method: z.literal('notifications/claude/channel/permission_request'),
+    params: z.object({
+        request_id: z.string(),
+        tool_name: z.string(),
+        description: z.string(),
+        input_preview: z.string(),
+    }),
+});
+mcp.server.setNotificationHandler(PermissionRequestSchema, async ({ params }) => {
+    sendToRouter({
+        type: 'reply',
+        text: [
+            `Permission request:`,
+            `Tool: ${params.tool_name}`,
+            `Action: ${params.description}`,
+            '',
+            `Reply "yes ${params.request_id}" or "no ${params.request_id}"`,
+        ].join('\n'),
+    });
+});
+// ---------- WebSocket connection to router ----------
+let ws = null;
+let reconnectTimer = null;
+const RECONNECT_DELAY = 3000;
+// permission reply detection (same pattern as official plugins)
+const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i;
+function sendToRouter(msg) {
+    if (ws?.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify(msg));
+    }
+}
+function connectToRouter() {
+    try {
+        ws = new WebSocket(ROUTER_URL);
+        ws.onopen = () => {
+            console.error(`[bridge:${AGENT_NAME}] Connected to router`);
+            // register ourselves
+            sendToRouter({ type: 'register', name: AGENT_NAME });
+            // clear any reconnect timer
+            if (reconnectTimer) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = null;
+            }
+        };
+        ws.onmessage = async (event) => {
+            try {
+                const msg = JSON.parse(String(event.data));
+                if (msg.type === 'registered') {
+                    console.error(`[bridge:${AGENT_NAME}] Registered with router as "${msg.name}"`);
+                }
+                if (msg.type === 'message') {
+                    const text = String(msg.text ?? '');
+                    const chatId = String(msg.chatId ?? '');
+                    const senderName = String(msg.senderName ?? 'user');
+                    // check for permission reply
+                    const m = PERMISSION_REPLY_RE.exec(text);
+                    if (m) {
+                        await mcp.server.notification({
+                            method: 'notifications/claude/channel/permission',
+                            params: {
+                                request_id: m[2].toLowerCase(),
+                                behavior: m[1].toLowerCase().startsWith('y') ? 'allow' : 'deny',
+                            },
+                        });
+                        return;
+                    }
+                    // forward as channel notification to Claude
+                    await mcp.server.notification({
+                        method: 'notifications/claude/channel',
+                        params: {
+                            content: text,
+                            meta: {
+                                sender: senderName,
+                                chat_id: chatId,
+                            },
+                        },
+                    });
+                }
+            }
+            catch (err) {
+                console.error(`[bridge:${AGENT_NAME}] Error handling message:`, err);
+            }
+        };
+        ws.onclose = () => {
+            console.error(`[bridge:${AGENT_NAME}] Disconnected from router, reconnecting in ${RECONNECT_DELAY}ms...`);
+            scheduleReconnect();
+        };
+        ws.onerror = (err) => {
+            console.error(`[bridge:${AGENT_NAME}] WebSocket error:`, err);
+        };
+    }
+    catch (err) {
+        console.error(`[bridge:${AGENT_NAME}] Failed to connect:`, err);
+        scheduleReconnect();
+    }
+}
+function scheduleReconnect() {
+    if (reconnectTimer)
+        return;
+    reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        connectToRouter();
+    }, RECONNECT_DELAY);
+}
+// ---------- startup ----------
+// connect to Claude Code over stdio
+await mcp.connect(new StdioServerTransport());
+// connect to the router
+connectToRouter();
+// cleanup on exit
+process.on('SIGINT', () => {
+    ws?.close();
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    ws?.close();
+    process.exit(0);
+});

package/dist/clients/telegram.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Telegram messaging client for claude-mux router.
+ *
+ * Handles Telegram Bot API polling, auto-pairing, sender allowlist,
+ * and message chunking (4096 char limit).
+ */
+import type { MessagingClient, OnMessageCallback } from '../messaging-client.js';
+export declare class TelegramClient implements MessagingClient {
+    private readonly tgApi;
+    private readonly allowedUserIds;
+    private pairedChatId;
+    private messageCallback;
+    private offset;
+    constructor(opts: {
+        botToken: string;
+        allowedUserIds?: number[];
+    });
+    /** The paired chat ID, if any. Useful for the router to know where to send unsolicited messages. */
+    get chatId(): string | null;
+    onMessage(callback: OnMessageCallback): void;
+    sendMessage(chatId: string, text: string): Promise<void>;
+    start(): Promise<void>;
+    private tgCall;
+    private pollOnce;
+}

package/dist/clients/telegram.js

@@ -0,0 +1,109 @@
+/**
+ * Telegram messaging client for claude-mux router.
+ *
+ * Handles Telegram Bot API polling, auto-pairing, sender allowlist,
+ * and message chunking (4096 char limit).
+ */
+// ---------- client ----------
+export class TelegramClient {
+    tgApi;
+    allowedUserIds;
+    pairedChatId = null;
+    messageCallback = null;
+    offset = 0;
+    constructor(opts) {
+        this.tgApi = `https://api.telegram.org/bot${opts.botToken}`;
+        this.allowedUserIds = new Set(opts.allowedUserIds ?? []);
+    }
+    /** The paired chat ID, if any. Useful for the router to know where to send unsolicited messages. */
+    get chatId() {
+        return this.pairedChatId !== null ? String(this.pairedChatId) : null;
+    }
+    onMessage(callback) {
+        this.messageCallback = callback;
+    }
+    async sendMessage(chatId, text) {
+        const numericChatId = parseInt(chatId, 10);
+        // split long messages (telegram limit 4096 chars)
+        const chunks = [];
+        let remaining = text;
+        while (remaining.length > 0) {
+            if (remaining.length <= 4096) {
+                chunks.push(remaining);
+                break;
+            }
+            let breakAt = remaining.lastIndexOf('\n', 4096);
+            if (breakAt < 2000)
+                breakAt = 4096;
+            chunks.push(remaining.slice(0, breakAt));
+            remaining = remaining.slice(breakAt);
+        }
+        for (const chunk of chunks) {
+            await this.tgCall('sendMessage', { chat_id: numericChatId, text: chunk });
+        }
+    }
+    async start() {
+        console.log('[telegram] Starting poll loop...');
+        while (true) {
+            await this.pollOnce();
+        }
+    }
+    // ---------- internals ----------
+    async tgCall(method, body) {
+        const resp = await fetch(`${this.tgApi}/${method}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const json = (await resp.json());
+        if (!json.ok) {
+            console.error(`Telegram API error (${method}):`, json.description);
+        }
+        return json.result;
+    }
+    async pollOnce() {
+        try {
+            const result = await this.tgCall('getUpdates', {
+                offset: this.offset,
+                timeout: 30,
+                allowed_updates: ['message'],
+            });
+            if (!result)
+                return;
+            for (const update of result) {
+                this.offset = update.update_id + 1;
+                const msg = update.message;
+                if (!msg?.text)
+                    continue;
+                const senderId = msg.from.id;
+                const chatId = msg.chat.id;
+                // sender gating
+                if (this.allowedUserIds.size > 0 && !this.allowedUserIds.has(senderId)) {
+                    continue;
+                }
+                // auto-pair: remember the chat id for replies
+                if (this.pairedChatId === null) {
+                    this.pairedChatId = chatId;
+                    if (this.allowedUserIds.size === 0) {
+                        this.allowedUserIds.add(senderId);
+                    }
+                    await this.sendMessage(String(chatId), `Paired! Your user ID ${senderId} is now allowed.\nUse /help to see commands.`);
+                    continue;
+                }
+                console.log(`[telegram] Received: "${msg.text}" from ${msg.from.first_name ?? msg.from.username ?? senderId}`);
+                // deliver to router
+                if (this.messageCallback) {
+                    await this.messageCallback({
+                        text: msg.text,
+                        chatId: String(chatId),
+                        senderId: String(senderId),
+                        senderName: msg.from.first_name ?? msg.from.username ?? String(senderId),
+                    });
+                }
+            }
+        }
+        catch (err) {
+            console.error('[telegram] Poll error:', err);
+        }
+    }
+}

package/dist/core-router.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Core router for claude-mux.
+ *
+ * Handles agent management, command handling, fuzzy/LLM matching,
+ * and the WebSocket server for bridges. Platform-agnostic — communicates
+ * with users through a MessagingClient interface.
+ */
+import { type LanguageModel } from 'ai';
+import type { MessagingClient } from './messaging-client.js';
+export declare class Router {
+    private readonly client;
+    private readonly model;
+    private readonly port;
+    private readonly host;
+    private readonly agents;
+    private readonly wsBySocket;
+    private activeAgent;
+    private defaultChatId;
+    constructor(opts: {
+        client: MessagingClient;
+        model?: LanguageModel;
+        port?: number;
+        host?: string;
+    });
+    start(): Promise<void>;
+    private handleInboundMessage;
+    private llmMatchAgent;
+    private detectSwitchIntent;
+    private listAgents;
+    private fuzzyMatchAgent;
+    private switchAgent;
+    private statusMessage;
+    private parseCommand;
+    private handleCommand;
+    private handleHttpRequest;
+    private handleWsMessage;
+    private handleWsClose;
+}

package/dist/core-router.js

@@ -0,0 +1,375 @@
+/**
+ * Core router for claude-mux.
+ *
+ * Handles agent management, command handling, fuzzy/LLM matching,
+ * and the WebSocket server for bridges. Platform-agnostic — communicates
+ * with users through a MessagingClient interface.
+ */
+import { generateText, generateObject } from 'ai';
+import { z } from 'zod';
+import { createServer } from 'http';
+import { WebSocketServer } from 'ws';
+// ---------- router ----------
+export class Router {
+    client;
+    model;
+    port;
+    host;
+    agents = new Map();
+    wsBySocket = new Map();
+    activeAgent = null;
+    defaultChatId = null;
+    constructor(opts) {
+        this.client = opts.client;
+        this.model = opts.model ?? null;
+        this.port = opts.port ?? 9900;
+        this.host = opts.host ?? '127.0.0.1';
+        if (this.model) {
+            const modelId = typeof this.model === 'string' ? this.model : this.model.modelId;
+            console.log(`[router] LLM routing enabled (${modelId})`);
+        }
+        else {
+            console.log('[router] LLM routing disabled (no model provided). Using fuzzy match only.');
+        }
+    }
+    async start() {
+        // wire up inbound messages from the client
+        this.client.onMessage(this.handleInboundMessage.bind(this));
+        // start HTTP + WebSocket server
+        const httpServer = createServer(this.handleHttpRequest.bind(this));
+        const wss = new WebSocketServer({ server: httpServer, path: '/ws' });
+        wss.on('connection', (ws) => {
+            console.log('[router] Bridge connected');
+            ws.on('message', (raw) => this.handleWsMessage(ws, String(raw)));
+            ws.on('close', () => this.handleWsClose(ws));
+        });
+        httpServer.listen(this.port, this.host, () => {
+            console.log(`[router] Listening on ws://${this.host}:${this.port}/ws`);
+        });
+        // start the messaging client (blocking — e.g. Telegram poll loop)
+        await this.client.start();
+    }
+    // ---------- inbound message dispatch ----------
+    async handleInboundMessage(msg) {
+        // remember the chat for unsolicited messages (bridge replies, connect/disconnect)
+        if (this.defaultChatId === null) {
+            this.defaultChatId = msg.chatId;
+        }
+        // handle commands — ALL /commands stay in the router, never forwarded
+        if (msg.text.startsWith('/')) {
+            const parsed = this.parseCommand(msg.text);
+            console.log(`[router] Command detected: ${parsed ? `/${parsed.command} args="${parsed.args}"` : `(parse failed: "${msg.text}")`}`);
+            await this.handleCommand(msg.chatId, msg.text);
+            return;
+        }
+        // natural language switch detection
+        if (this.model && this.agents.size > 1 && /\bswitch\b/i.test(msg.text)) {
+            console.log(`[router] "switch" keyword detected in: "${msg.text}", asking Haiku for intent...`);
+            const intent = await this.detectSwitchIntent(msg.text);
+            if (intent) {
+                console.log(`[router] Haiku detected switch intent, query: "${intent.query}"`);
+                await this.client.sendMessage(msg.chatId, await this.switchAgent(intent.query));
+                return;
+            }
+            console.log(`[router] Haiku says not a switch request, forwarding to agent`);
+        }
+        // route to active agent
+        if (!this.activeAgent || !this.agents.has(this.activeAgent)) {
+            if (this.agents.size === 1) {
+                this.activeAgent = this.agents.keys().next().value ?? null;
+                console.log(`[router] Auto-selected only agent: ${this.activeAgent}`);
+            }
+            else {
+                console.log(`[router] No active agent, ${this.agents.size} agents connected`);
+                await this.client.sendMessage(msg.chatId, this.agents.size === 0
+                    ? 'No agents connected. Start a Claude Code session with the bridge plugin.'
+                    : `Multiple agents connected. Use /switch <name> to pick one.\n${this.listAgents()}`);
+                return;
+            }
+        }
+        const agent = this.agents.get(this.activeAgent);
+        if (!agent)
+            return;
+        console.log(`[router] Forwarding to agent: ${this.activeAgent}`);
+        agent.ws.send(JSON.stringify({
+            type: 'message',
+            text: msg.text,
+            chatId: msg.chatId,
+            senderName: msg.senderName,
+        }));
+    }
+    // ---------- LLM routing ----------
+    async llmMatchAgent(query, agentNames) {
+        if (!this.model || agentNames.length === 0)
+            return null;
+        const prompt = `Agents:\n${agentNames.map(n => `- ${n}`).join('\n')}\n\nUser wants to switch to: "${query}"`;
+        console.log(`[llm] Request: ${prompt}`);
+        try {
+            const { text: result } = await generateText({
+                model: this.model,
+                maxOutputTokens: 100,
+                system: [
+                    'You are a routing assistant. Given a list of agent names (formatted as repo/branch) and a user query, ',
+                    'pick the single best matching agent. Respond with ONLY the exact agent name, nothing else. ',
+                    'If no agent matches at all, respond with "NONE".',
+                ].join(''),
+                prompt,
+            });
+            const trimmed = result.trim();
+            console.log(`[llm] Response: "${trimmed}"`);
+            if (trimmed === 'NONE')
+                return 'NONE';
+            if (agentNames.includes(trimmed)) {
+                console.log(`[llm] Exact match in agent list`);
+                return trimmed;
+            }
+            const lower = trimmed.toLowerCase();
+            const found = agentNames.find(n => n.toLowerCase() === lower);
+            if (found) {
+                console.log(`[llm] Case-insensitive match: "${found}"`);
+                return found;
+            }
+            console.log(`[llm] Response "${trimmed}" does not match any agent: [${agentNames.join(', ')}]`);
+            return null;
+        }
+        catch (err) {
+            console.error('[llm] LLM routing failed, falling back to fuzzy match:', err);
+            return null;
+        }
+    }
+    async detectSwitchIntent(text) {
+        if (!this.model)
+            return null;
+        try {
+            const { object: intent } = await generateObject({
+                model: this.model,
+                maxOutputTokens: 200,
+                system: [
+                    'You help route messages. The user is chatting with coding agents identified by repo/branch names. ',
+                    'Determine if this message is asking to switch to a different agent/worktree/repo/branch. ',
+                    'If YES: set intent to "switch" and query to the part describing which agent. ',
+                    'If NO (the word "switch" is part of a coding instruction like "switch statement" or "switch branches in git"): ',
+                    'set intent to "message".',
+                ].join(''),
+                schema: z.object({
+                    intent: z.enum(['switch', 'message']),
+                    query: z.string().optional(),
+                }),
+                prompt: `Connected agents:\n${[...this.agents.keys()].map(n => `- ${n}`).join('\n')}\n\nUser message: "${text}"`,
+            });
+            console.log(`[llm-intent] Response: ${JSON.stringify(intent)}`);
+            if (intent.intent === 'switch' && intent.query) {
+                return { query: intent.query };
+            }
+            return null;
+        }
+        catch (err) {
+            console.error('[llm-intent] Intent detection failed, forwarding as message:', err);
+            return null;
+        }
+    }
+    // ---------- command handling ----------
+    listAgents() {
+        if (this.agents.size === 0)
+            return 'No agents connected.';
+        const lines = [];
+        for (const [name, agent] of this.agents) {
+            const marker = name === this.activeAgent ? ' (active)' : '';
+            const uptime = Math.round((Date.now() - agent.registeredAt.getTime()) / 60000);
+            lines.push(`  ${name}${marker} — up ${uptime}m`);
+        }
+        return `Connected agents:\n${lines.join('\n')}`;
+    }
+    fuzzyMatchAgent(query) {
+        const queryTokens = query.toLowerCase().split(/[\s\/\-_]+/).filter(Boolean);
+        if (queryTokens.length === 0)
+            return [];
+        const results = [];
+        for (const agentName of this.agents.keys()) {
+            const nameTokens = agentName.toLowerCase().split(/[\s\/\-_]+/).filter(Boolean);
+            const nameLower = agentName.toLowerCase();
+            let score = 0;
+            if (nameLower === query.toLowerCase()) {
+                score = 1000;
+            }
+            else {
+                for (const qt of queryTokens) {
+                    if (nameTokens.includes(qt)) {
+                        score += 10;
+                    }
+                    else if (nameTokens.some(nt => nt.startsWith(qt))) {
+                        score += 7;
+                    }
+                    else if (nameLower.includes(qt)) {
+                        score += 4;
+                    }
+                    else if (nameTokens.some(nt => qt.startsWith(nt))) {
+                        score += 2;
+                    }
+                }
+            }
+            if (score > 0) {
+                results.push({ name: agentName, score });
+            }
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results;
+    }
+    async switchAgent(query) {
+        console.log(`[switch] Query: "${query}"`);
+        console.log(`[switch] Connected agents: [${[...this.agents.keys()].join(', ')}]`);
+        if (this.agents.has(query)) {
+            this.activeAgent = query;
+            console.log(`[switch] Exact match → ${query}`);
+            return `Switched to ${query}`;
+        }
+        const agentNames = [...this.agents.keys()];
+        if (this.model) {
+            console.log(`[switch] No exact match, calling LLM...`);
+            const llmResult = await this.llmMatchAgent(query, agentNames);
+            if (llmResult && llmResult !== 'NONE') {
+                this.activeAgent = llmResult;
+                console.log(`[switch] Haiku matched → ${llmResult}`);
+                return `Switched to ${llmResult}`;
+            }
+            if (llmResult === 'NONE') {
+                console.log(`[switch] Haiku says no match`);
+                const available = agentNames.join('\n  ') || 'none';
+                return `No agent matches "${query}". Connected:\n  ${available}`;
+            }
+            console.log('[switch] Haiku unavailable, falling back to fuzzy match');
+        }
+        const matches = this.fuzzyMatchAgent(query);
+        console.log(`[switch] Fuzzy matches: ${JSON.stringify(matches.slice(0, 5))}`);
+        if (matches.length === 0) {
+            console.log(`[switch] No fuzzy matches`);
+            const available = agentNames.join('\n  ') || 'none';
+            return `No agent matches "${query}". Connected:\n  ${available}`;
+        }
+        if (matches.length === 1 || matches[0].score >= matches[1].score * 1.5) {
+            this.activeAgent = matches[0].name;
+            console.log(`[switch] Fuzzy matched → ${matches[0].name} (score: ${matches[0].score})`);
+            return `Switched to ${matches[0].name}`;
+        }
+        console.log(`[switch] Ambiguous, showing options`);
+        const options = matches.slice(0, 5)
+            .map((m, i) => `  ${i + 1}. ${m.name}`)
+            .join('\n');
+        return `Multiple matches for "${query}":\n${options}\n\nBe more specific, or use /switch with the full name.`;
+    }
+    statusMessage() {
+        const active = this.activeAgent && this.agents.has(this.activeAgent) ? this.activeAgent : 'none';
+        return `Active: ${active}\nTotal agents: ${this.agents.size}`;
+    }
+    parseCommand(text) {
+        const trimmed = text.trim();
+        if (!trimmed.startsWith('/'))
+            return null;
+        // strip @bot_name suffix (Telegram convention, harmless for other platforms)
+        const match = trimmed.match(/^\/(\w+)(?:@\S+)?\s*(.*)$/s);
+        if (!match)
+            return null;
+        return { command: match[1].toLowerCase(), args: match[2].trim() };
+    }
+    async handleCommand(chatId, text) {
+        const parsed = this.parseCommand(text);
+        if (!parsed)
+            return false;
+        switch (parsed.command) {
+            case 'list':
+                await this.client.sendMessage(chatId, this.listAgents());
+                return true;
+            case 'status':
+                await this.client.sendMessage(chatId, this.statusMessage());
+                return true;
+            case 'switch':
+                if (!parsed.args) {
+                    await this.client.sendMessage(chatId, 'Usage: /switch <agent-name>');
+                }
+                else {
+                    await this.client.sendMessage(chatId, await this.switchAgent(parsed.args));
+                }
+                return true;
+            case 'help':
+            case 'start':
+                await this.client.sendMessage(chatId, [
+                    'Commands:',
+                    '  /list — show connected agents',
+                    '  /switch <name> — route messages to an agent',
+                    '  /status — show current routing',
+                    '  /help — this message',
+                    '',
+                    'Any other message goes to the active agent.',
+                ].join('\n'));
+                return true;
+            default:
+                await this.client.sendMessage(chatId, `Unknown command: /${parsed.command}\nType /help for available commands.`);
+                return true;
+        }
+    }
+    // ---------- HTTP ----------
+    handleHttpRequest(_req, res) {
+        if (_req.url === '/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                agents: [...this.agents.keys()],
+                activeAgent: this.activeAgent,
+                paired: this.defaultChatId !== null,
+            }));
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('claude-mux router');
+    }
+    // ---------- WebSocket (bridges) ----------
+    handleWsMessage(ws, raw) {
+        try {
+            const msg = JSON.parse(raw);
+            if (msg.type === 'register') {
+                const name = String(msg.name);
+                if (this.agents.has(name)) {
+                    const old = this.agents.get(name);
+                    this.wsBySocket.delete(old.ws);
+                    try {
+                        old.ws.close();
+                    }
+                    catch { }
+                }
+                const agent = { name, ws, registeredAt: new Date() };
+                this.agents.set(name, agent);
+                this.wsBySocket.set(ws, agent);
+                console.log(`[router] Agent registered: ${name} (total: ${this.agents.size})`);
+                if (this.agents.size === 1)
+                    this.activeAgent = name;
+                if (this.defaultChatId) {
+                    this.client.sendMessage(this.defaultChatId, `Agent "${name}" connected.${this.activeAgent === name ? ' (active)' : ` Use /switch ${name} to activate.`}`);
+                }
+                ws.send(JSON.stringify({ type: 'registered', name }));
+            }
+            if (msg.type === 'reply' || msg.type === 'notify') {
+                if (!this.defaultChatId)
+                    return;
+                const agentInfo = this.wsBySocket.get(ws);
+                const prefix = agentInfo ? `[${agentInfo.name}] ` : '';
+                this.client.sendMessage(this.defaultChatId, `${prefix}${String(msg.text)}`);
+            }
+        }
+        catch (err) {
+            console.error('[router] Bad message from bridge:', err);
+        }
+    }
+    handleWsClose(ws) {
+        const agent = this.wsBySocket.get(ws);
+        if (agent) {
+            this.agents.delete(agent.name);
+            this.wsBySocket.delete(ws);
+            console.log(`[router] Agent disconnected: ${agent.name} (total: ${this.agents.size})`);
+            if (this.activeAgent === agent.name) {
+                this.activeAgent = this.agents.size > 0 ? this.agents.keys().next().value ?? null : null;
+            }
+            if (this.defaultChatId) {
+                this.client.sendMessage(this.defaultChatId, `Agent "${agent.name}" disconnected.${this.activeAgent ? ` Active: ${this.activeAgent}` : ''}`);
+            }
+        }
+    }
+}

package/dist/messaging-client.d.ts

@@ -0,0 +1,23 @@
+/** A message received from the messaging platform */
+export interface InboundMessage {
+    text: string;
+    chatId: string;
+    senderId: string;
+    senderName: string;
+}
+/** Callback the client calls when a message arrives */
+export type OnMessageCallback = (msg: InboundMessage) => Promise<void>;
+/**
+ * Interface that any messaging platform must implement.
+ * The router calls sendMessage(); the client calls onMessage() when a user sends something.
+ */
+export interface MessagingClient {
+    /** Send text to a chat. The client handles platform-specific chunking/limits. */
+    sendMessage(chatId: string, text: string): Promise<void>;
+    /** Register the handler the router will use to receive messages */
+    onMessage(callback: OnMessageCallback): void;
+    /** Start the client (polling, webhook, etc). Called once by the router. */
+    start(): Promise<void>;
+    /** Optional cleanup */
+    stop?(): Promise<void>;
+}

package/dist/messaging-client.js

@@ -0,0 +1 @@
+export {};

package/dist/router.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * claude-mux router entrypoint
+ *
+ * Loads config from .env, creates a Telegram client and core router,
+ * and starts everything. Swap TelegramClient for another MessagingClient
+ * implementation to support Discord, Slack, WhatsApp, etc.
+ *
+ * LLM provider is configured via ROUTER_MODEL env var:
+ *   anthropic:claude-haiku-4-5-20251001  (default if ANTHROPIC_API_KEY is set)
+ *   openai:gpt-5.4-nano
+ *   google:gemini-3.1-flash-lite-preview
+ */
+export {};

package/dist/router.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * claude-mux router entrypoint
+ *
+ * Loads config from .env, creates a Telegram client and core router,
+ * and starts everything. Swap TelegramClient for another MessagingClient
+ * implementation to support Discord, Slack, WhatsApp, etc.
+ *
+ * LLM provider is configured via ROUTER_MODEL env var:
+ *   anthropic:claude-haiku-4-5-20251001  (default if ANTHROPIC_API_KEY is set)
+ *   openai:gpt-5.4-nano
+ *   google:gemini-3.1-flash-lite-preview
+ */
+import { config } from 'dotenv';
+config();
+import { Router } from './core-router.js';
+import { TelegramClient } from './clients/telegram.js';
+const botToken = process.env.TELEGRAM_BOT_TOKEN;
+if (!botToken) {
+    console.error('TELEGRAM_BOT_TOKEN is required');
+    process.exit(1);
+}
+// ---------- LLM model ----------
+async function createModel() {
+    const modelSpec = process.env.ROUTER_MODEL;
+    if (modelSpec) {
+        const [provider, ...rest] = modelSpec.split(':');
+        const modelId = rest.join(':');
+        if (!modelId) {
+            console.error(`Invalid ROUTER_MODEL format: "${modelSpec}". Expected "provider:model-id".`);
+            process.exit(1);
+        }
+        switch (provider) {
+            case 'anthropic': {
+                const { createAnthropic } = await import('@ai-sdk/anthropic');
+                return createAnthropic()(modelId);
+            }
+            case 'openai': {
+                const { createOpenAI } = await import('@ai-sdk/openai');
+                return createOpenAI()(modelId);
+            }
+            case 'google': {
+                const { createGoogleGenerativeAI } = await import('@ai-sdk/google');
+                return createGoogleGenerativeAI()(modelId);
+            }
+            default:
+                console.error(`Unknown LLM provider: "${provider}". Supported: anthropic, openai, google.`);
+                process.exit(1);
+        }
+    }
+    // default: use Anthropic Haiku if API key is available
+    if (process.env.ANTHROPIC_API_KEY) {
+        const { createAnthropic } = await import('@ai-sdk/anthropic');
+        return createAnthropic()('claude-haiku-4-5-20251001');
+    }
+    return undefined;
+}
+// ---------- start ----------
+const allowedUserIds = process.env.ALLOWED_USER_IDS
+    ?.split(',')
+    .map(id => parseInt(id.trim(), 10));
+const client = new TelegramClient({ botToken, allowedUserIds });
+const router = new Router({
+    client,
+    model: await createModel(),
+    port: parseInt(process.env.ROUTER_PORT ?? '9900', 10),
+    host: process.env.ROUTER_HOST ?? '127.0.0.1',
+});
+router.start();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "claude-code-mux",
+  "version": "0.1.0",
+  "description": "One messaging client, many Claude Code agents — a multiplexer for routing messages to multiple Claude Code sessions",
+  "type": "module",
+  "bin": {
+    "claude-mux-router": "./dist/router.js",
+    "claude-mux-bridge": "./dist/bridge.js"
+  },
+  "files": [
+    "dist",
+    "demo.png"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "router": "tsx src/router.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "telegram",
+    "multiplexer",
+    "agent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.63",
+    "@ai-sdk/google": "^3.0.53",
+    "@ai-sdk/openai": "^3.0.48",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ai": "^6.0.137",
+    "dotenv": "^16.4.0",
+    "ws": "^8.18.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}