claude-channel-mux

claude-channel-mux

Multi-channel, multi-agent session multiplexer for Claude Code and Codex. One lightweight daemon routes Slack + Telegram conversations to CCM rooms; each room owns a cwd, a default agent, and lazily-created agent sessions.

Talk to Claude Code or Codex from your phone. Let multiple agents coexist in one Slack/Telegram thread, with visible agent identity headers and on-demand context fetching instead of daemon-side conversation memory.

Architecture

Slack / Telegram
      │
      ▼
ChannelAdapter (platform send/receive, files, reactions, buttons)
      │
      ▼
daemon.ts
  - lightweight room router: cwd, default agent, lazy slots
  - no daemon conversation memory or unread peer inbox
  - visible identity headers for shared transcript UX
      │
      ▼
AgentRegistry / AgentDriver SPI
      ├─ ClaudeChannelAgentDriver
      │    wraps the existing Claude Code channel/MCP notification bridge
      │    because Claude Code has no Codex-style app-server inbound API
      └─ CodexAppServerAgentDriver
           owns `codex app-server --listen stdio://`, sends `turn/start`,
           receives app-server events, and injects the CCM MCP server

Key components

File	Role
daemon.ts	Core orchestrator: room commands, bindings, lazy session lifecycle, Agent SPI routing
agents/types.ts	Shared Agent SPI types: sessions, turns, capabilities, events
agents/registry.ts	Runtime registry for current and future agent drivers
agents/claude/channel-driver.ts	Claude driver that encapsulates current channel notification transport
agents/codex/app-server-driver.ts	Codex driver that uses Codex App Server for inbound/session/events
agents/codex/app-server-client.ts	Minimal stdio JSON client for codex app-server
server.ts	Per-agent MCP bridge and tools: reply, react, edit, attachment, fetch_thread
adapters/types.ts	ChannelAdapter interface
adapters/slack.ts	Slack Socket Mode + Web API + slash commands + modal search
adapters/telegram.ts	Telegram Bot API long poll + force_reply search + bot commands
escort.ts / zellij-plugin/	Claude UI support: zellij helpers and optional pane watcher

Claude and Codex intentionally share the same high-level SPI, not the same low-level transport. Codex can be cleanly app-server driven. Claude is encapsulated behind ClaudeChannelAgentDriver, but internally still needs channel notification support from server.ts; a plugin/MCP tool alone is not enough to deliver inbound user turns to Claude Code.

Features

• Multi-room, multi-agent - Each Slack/Telegram room can host Claude and Codex side by side
• Lazy agent slots - ccm /repo binds the room; claude: or codex: starts that agent only when cued
• Inline keyboard navigation - Claude Code startup dialogs rendered as chat buttons
• Directory picker - Browse, search, and jump to directories from chat
• Session picker - Two-level menu (project folders, then sessions) with title extraction
• Image/file support - Bidirectional: send images to agents, agents send files back
• Permission forwarding - Claude Code permission prompts appear as Allow/Deny buttons in chat; undeliverable prompts fail closed as Deny
• Git worktree isolation - Optional per-session worktree branches
• Shared transcript UX - Agent replies are prepended with identity headers (🟣 Claude, 🟢 Codex) so users and peer agents can see who said what
• Slash commands - Native /ccm, /cc, and /cx commands (Slack + Telegram)
• Fault tolerant - IPC auto-reconnect, daemon restart recovery, stale tab cleanup

Commands

Type in any connected Slack channel or Telegram chat (plain text or /ccm slash command):

Command	Action
ccm	Directory picker for the room
ccm /path/to/dir	Bind this room to a cwd; does not start agents
claude: ... / @claude ...	Send a turn to Claude, lazy-starting its slot if needed
codex: ... / @codex ...	Send a turn to Codex, lazy-starting its slot if needed
`ccm default claude	codex`
@agents ... / agents: ...	Fan out one turn to all agent slots, without recursive auto-rounds
ccm agents	Show room cwd, default agent, and agent slot status
ccm route	Explain how the next plain message routes
ccm new [agent] / ccm start [agent]	Start a fresh agent slot session in this room
ccm resume [agent|id]	Interactive session picker, or resume a specific session into this room
ccm stop [agent|id]	Stop one agent slot session; if other rooms reference it, unbind those rooms first
ccm find <query>	Fuzzy search directories
ccm help	Status + commands + action buttons

Claude Code terminal commands (forwarded only to the Claude slot):