cc-mess

cc-mess

Inter-Claude-Code communication plugin — mesh networking for multiple Claude Code instances. Enables discovery, communication, task delegation, and emergent trust relationships using a file-based transport layer and symmetric peer architecture.

Note: cc-mess uses Claude Code's Channels feature (research preview) for real-time message delivery between instances. Channels are experimental and require the --dangerously-load-development-channels flag. The API and behavior may change in future Claude Code releases.

Architecture

graph TD
    Human[Human via Telegram] <-->|cc-telegram-plus| Coordinator
    Coordinator[Coordinator Instance<br/>apollo-3f2a] <-->|file-based inbox| WorkerA[Worker<br/>hermes-c1b7]
    Coordinator <-->|file-based inbox| WorkerB[Worker<br/>athena-9d4e]
    WorkerA <-->|peer-to-peer| WorkerB

    subgraph "~/.claude/channels/mess/"
        Registry[registry.json]
        Control[control.json]
        Config[config.json]
        Inboxes[inboxes/]
    end

    Coordinator --- Registry
    WorkerA --- Inboxes
    WorkerB --- Inboxes

Setup

1. Build cc-mess

cd /path/to/cc-mess
npm install
npm run build

2. Add to your project

In your project directory, create .mcp.json:

{
  "mcpServers": {
    "cc-mess": {
      "command": "node",
      "args": ["/path/to/cc-mess/dist/server.js"],
      "env": {}
    }
  }
}

3. Configure the mesh

Create ~/.claude/channels/mess/config.json:

{
  "allowed_directories": ["/path/to/your/projects/*"],
  "max_instances": 10,
  "max_spawn_depth": 3,
  "require_telegram_relay": false,
  "default_guardrail": "permissive"
}

Set require_telegram_relay: true if you want to enforce Telegram visibility before workers can be spawned.

4. Pre-allow MCP tools

In your project's .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__cc-mess__list_instances",
      "mcp__cc-mess__send",
      "mcp__cc-mess__broadcast",
      "mcp__cc-mess__reply",
      "mcp__cc-mess__spawn",
      "mcp__cc-mess__kill",
      "mcp__cc-mess__update_self",
      "mcp__cc-mess__mesh_control",
      "mcp__cc-mess__send_as_human"
    ]
  }
}

Running

Start the coordinator

The --dangerously-load-development-channels server:cc-mess flag is required for instances to receive messages from each other. Without it, MCP tools work but channel notifications (inbound messages) are silently dropped.

CC_MESS_ROLE=coordinator claude --dangerously-load-development-channels server:cc-mess

Start a worker (interactive)

In another terminal, from the same project directory:

CC_MESS_ROLE=worker claude --dangerously-load-development-channels server:cc-mess

Start a worker (one-shot task)

CC_MESS_ROLE=worker claude --dangerously-load-development-channels server:cc-mess \
  "You are a mesh worker. Call list_instances to see the mesh, then do your assigned task."

Tmux dashboard

Launch a full dashboard with coordinator, viewer, and auto-created worker panes:

npm run dashboard -- --no-telegram --clean

• --no-telegram — disable the Telegram relay requirement for spawning
• --clean — wipe previous mesh state (registry, inboxes, audit) and start fresh

Workers spawned from the coordinator automatically appear as interactive panes in the dashboard.

Conversation viewer

View the message timeline between instances:

npm run viewer                    # show all messages
npm run viewer -- --follow        # live-tail new messages
npm run viewer -- --last 20       # show last 20 messages
npm run viewer -- --from hermes   # filter by sender

Spawn a worker from the coordinator

Inside the coordinator session:

spawn(cwd: "/path/to/project", task: "Refactor the auth module")

This launches a new Claude Code process with the cc-mess plugin injected automatically.

MCP Tools

Tool	Purpose
send	Send a message to a specific instance by name
broadcast	Send a message to all instances (or filtered subset)
reply	Reply to a received message (threads via in_reply_to)
list_instances	Show the current registry — who's alive, what they're doing
spawn	Launch a new Claude Code instance with a task
kill	Ask an instance to gracefully shut down
update_self	Update own registry entry (task, capabilities)
mesh_control	Pause, resume, or shut down the entire mesh (coordinator only)
send_as_human	Route a Telegram message to an instance as the human (coordinator only)

Telegram Integration