File-based agent-to-agent communication between Claude Code instances running on the same machine.
Two Claude Code sessions can't talk to each other. CC2CC fixes that with a file mailbox + MCP push channel.
Extracted from a working multi-agent setup. Built on Claude Code hooks, MCP channels, and plain JSON files.
⚠️ Experimental: CC2CC relies on Claude Code's development channels — an experimental feature not yet publicly stable. You must launch Claude Code with the--dangerously-load-development-channelsflag for channel push notifications to work. Without it, the MCP server starts but cannot push messages into the session.Tested with Claude Code v2.1.86. Channel API may change in future versions.
5 Claude Code agents debating in split panes via cc2cc:
demo.mp4
- A devops agent and a coding agent collaborating on the same project
- A monitoring agent that alerts a main agent when something breaks
- Two agents with different tool access splitting a complex task
- An always-on agent delegating subtasks to a specialist
┌─────────────────┐ ┌─────────────────┐
│ Claude Code A │ │ Claude Code B │
│ (auto: brave-fox)│ │ (auto: calm-owl)│
│ │ │ │
│ MCP Server ◄────┼─── to-brave-fox/inbox/ ◄─────┼── send tool │
│ (polls inbox) │ │ │
│ send tool ──────┼──► to-calm-owl/inbox/ ───────┼──► MCP Server │
│ │ │ (polls inbox) │
│ Tools: │ status/ │ Tools: │
│ send, broadcast │ brave-fox-heartbeat.json │ send, broadcast │
│ reply, register │ calm-owl-heartbeat.json │ reply, register │
│ list_agents │ │ list_agents │
│ whoami │ │ whoami │
└─────────────────┘ └─────────────────┘
How it works: Agent A drops a JSON file into an inbox directory. Agent B's MCP server polls that directory, reads the message, and pushes it into B's session as a channel notification. B replies using an MCP tool, which writes a response back into A's inbox. Messages for offline agents wait in the inbox and get delivered on the next session start.
The easy way: copy this prompt, paste it into any Claude Code session — Claude does the rest!
Install cc2cc — a file-based agent-to-agent messaging system that lets
multiple Claude Code sessions communicate with each other on the same machine.
Steps:
1. Clone: git clone https://github.com/non4me/cc2cc.git ~/.cc2cc/repo
2. Install deps: cd ~/.cc2cc/repo/channel && npm install
3. Copy server files to bridge:
cp ~/.cc2cc/repo/channel/server.mjs ~/.cc2cc/server.mjs
cp ~/.cc2cc/repo/channel/names.mjs ~/.cc2cc/names.mjs
cp ~/.cc2cc/repo/channel/package.json ~/.cc2cc/package.json
cp -r ~/.cc2cc/repo/channel/node_modules ~/.cc2cc/node_modules
4. Create status dir: mkdir -p ~/.cc2cc/status
5. Add MCP server to ~/.claude.json (mcpServers section):
"cc2cc": {
"command": "node",
"args": ["~/.cc2cc/server.mjs"],
"env": { "CC2CC_BRIDGE_DIR": "~/.cc2cc" }
}
6. Verify: run "node ~/.cc2cc/server.mjs" to check it starts without errors.
After install, restart Claude Code with:
claude --dangerously-load-development-channels server:cc2cc
Manual installation
- Claude Code (CLI)
- Node.js ≥ 18 (for the MCP channel server)
- Python 3.8+ (for scripts)
git clone https://github.com/non4me/cc2cc.git
cd cc2cc
pip install -e .
cc2cc initAdd to ~/.claude/settings.json:
{
"mcpServers": {
"cc2cc": {
"command": "node",
"args": ["~/.cc2cc/server.mjs"],
"env": {
"CC2CC_BRIDGE_DIR": "~/.cc2cc"
}
}
}
}Every Claude Code instance you open will auto-register with a unique name and discover other agents automatically.
# Terminal 1
claude --dangerously-load-development-channels server:cc2cc
# You'll see: [cc2cc] You are brave-fox. No other agents online
# Terminal 2
claude --dangerously-load-development-channels server:cc2cc
# You'll see: [cc2cc] You are calm-owl. Online agents: brave-fox
# Terminal 1 sees: [cc2cc] calm-owl joinedNote: The
--dangerously-load-development-channels server:cc2ccflag is required for the MCP server to push incoming messages into your Claude Code session. Without it, agents can send messages but won't receive them in real time. Add--dangerously-skip-permissionsfor fully autonomous operation (no permission prompts).
The agent can use MCP tools directly:
send(to="brave-fox", text="Hello!")— send to specific agentbroadcast(text="Deploy starting")— send to allreply(msg_id="msg-xxx", text="Got it")— reply to a messagelist_agents()— see who's onlinewhoami()— check your nameregister(name="devops")— change your name
| Feature | Google A2A | CC2CC |
|---|---|---|
| Transport | HTTP | Filesystem |
| Setup | Service discovery, auth, endpoints | cc2cc init |
| Dependencies | HTTP server per agent | Node.js (MCP server only) |
| Offline delivery | Requires message broker | Built-in (files wait in inbox) |
| Same-machine agents | Overkill | Purpose-built |
| Cross-network agents | ✅ | ❌ (same filesystem required) |
CC2CC is not a replacement for A2A. It's for the common case where you have multiple Claude Code instances on the same machine that need to coordinate.
cc2cc/
├── cc2cc/ # Python package
│ ├── __init__.py
│ ├── core.py # Atomic writes, bridge path, size limits
│ ├── signing.py # HMAC-SHA256 message signing
│ └── cli.py # Unified CLI entry point
├── pyproject.toml # pip installable package
├── channel/
│ ├── server.mjs # Unified MCP server (dynamic identity, multi-agent)
│ ├── names.mjs # Name generation (adjective-animal dictionary)
│ └── package.json
├── scripts/
│ ├── init.py # Bootstrap the bridge
│ ├── send.py # Send a message
│ ├── receive.py # Read pending messages
│ ├── reply.py # Reply to a message (completes tasks automatically)
│ ├── task.py # Delegate a task
│ ├── status.py # Show bridge status
│ ├── validate.py # Validate message schema
│ └── cleanup.py # TTL-based cleanup
├── hooks/
│ ├── session_start.py # SessionStart hook (heartbeat + inbox check)
│ ├── session_end.py # SessionEnd hook (mark offline)
│ └── inbox_watcher.py # Optional: watchdog-based real-time delivery
├── services/
│ ├── macos/ # LaunchAgent template (macOS)
│ ├── linux/ # systemd service template (Linux)
│ └── windows/ # Task Scheduler template (Windows)
├── tests/
│ └── test_smoke.py # Smoke tests
├── docs/
│ ├── SPECIFICATION.md # Protocol spec, schemas, message lifecycle
│ └── CONFIGURATION.md # Environment variables, full settings.json examples
├── LICENSE
└── README.md # ← you are here
| Platform | Status | Notes |
|---|---|---|
| macOS | Full support | watchdog or polling, LaunchAgent template |
| Linux | Full support | watchdog or polling, systemd template |
| Windows | Full support | watchdog or polling, Task Scheduler template |
- Same filesystem required — both agents must see
~/.cc2cc(local machine, NFS, or shared volume) - No authentication — any process that can write to the inbox can inject messages. See Security below.
- No encryption — messages are plaintext JSON
- No guaranteed ordering — use
replyTofor threading - Polling latency — up to 3s delivery delay (use watchdog for near-instant)
- Experimental MCP feature — requires
--dangerously-load-development-channelsflag; the channels API may change or be removed
CC2CC generates an HMAC-SHA256 shared secret during cc2cc init. All messages are signed automatically. Recipients verify signatures on read.
The secret is stored at ~/.cc2cc/secret.key. Protect it:
chmod 600 ~/.cc2cc/secret.key(macOS/Linux)- Restrict folder permissions (Windows)
Messages from processes without the secret will show [SIGNATURE INVALID] in receive output. Unsigned messages still work (backwards compatible) but are not verified.
Additional mitigations:
- Set restrictive permissions:
chmod 700 ~/.cc2cc - Only use on single-user machines where you trust all running processes
- Protocol Specification — message schema, agent cards, heartbeats, lifecycle
- Configuration Guide — environment variables, settings.json, scaling to N agents
- Google A2A Protocol — HTTP-based agent-to-agent
- MCP Channels — push notification mechanism used by the MCP server
- Claude Code Hooks — session lifecycle integration
See CONTRIBUTING.md for guidelines.
MIT — see LICENSE