distributed-coding-agent

Cross-machine Claude Code communication. Let CC sessions on different machines talk to each other — delegate tasks, sync results, and coordinate work automatically via a WebSocket relay mesh.

No more copy-pasting prompts between terminals. One CC session delegates, the other executes, results sync back.

Install

Install as a Claude Code plugin:

/plugin marketplace add zzzhouzhenzz/distributed-coding-agent
/plugin install distributed-coding-agent

Setup

Run /dca setup in a Claude Code session on each machine:

Machine A (Mac):

/dca setup
  What should I call this machine? [macbook]: macbook
  Peer address: 192.168.1.12
  Relay port [7800]: 7800
  Generated shared secret: abc123...
  Copy this to the other machine during its setup.

Machine B (Linux):

/dca setup
  What should I call this machine? [gpu-server]: gpu-server
  Peer address: 192.168.1.5
  Relay port [7800]: 7800
  Shared secret: abc123...
  Connected to macbook!

That's it. Both relays connect automatically. Config is saved for future sessions.

Usage

Just talk to Claude:

• "Delegate importing FB cookies to gpu-server" — Claude creates a task, sends it to the peer
• "Check on that task" — Claude checks status and message history
• "What tasks are active?" — Claude lists all tasks across machines
• "Tell gpu-server I pushed the new config" — Claude broadcasts a message (no task needed)

What Claude sees

At session start:

[distributed-coding-agent] I'm "macbook". Peer: connected.
  2 active task(s):
    - [in_progress] Import FB cookies (→ gpu-server)
    - [pending] Run benchmark suite (→ gpu-server)

MCP tools

Tool	What it does
delegate_task(peer, title, details)	Create a task assigned to a peer machine
check_task(task_id)	Get task status + full message history
list_tasks(status?)	List tasks, optionally filtered by status
respond_to_task(task_id, message, type?)	Add a response, question, or status update to a task
complete_task(task_id, summary)	Mark a task done with a summary
broadcast(message)	Send an info message to the peer (not a task)
get_peer_status()	Check if the peer is connected

Slash commands

Command	What it does
/dca setup	Interactive config — connect to a peer machine
/dca status	Show identity, peer status, active tasks
/dca send <peer> <message>	Quick task delegation from the terminal
/dca stop	Stop the relay daemon

Architecture

Machine A (Mac)                          Machine B (Linux)
┌─────────────────┐                      ┌─────────────────┐
│  CC Session      │                      │  CC Session      │
│  (MCP tools)     │                      │  (MCP tools)     │
└────────┬────────┘                      └────────┬────────┘
         │ localhost:7800                          │ localhost:7800
┌────────▼────────┐    WebSocket          ┌────────▼────────┐
│  Relay Server    │◄────────────────────►│  Relay Server    │
│  (FastAPI)       │    (persistent)       │  (FastAPI)       │
│  ┌────────────┐  │                      │  ┌────────────┐  │
│  │  SQLite    │  │                      │  │  SQLite    │  │
│  │  - tasks   │  │                      │  │  - tasks   │  │
│  │  - messages│  │                      │  │  - messages│  │
│  │  - config  │  │                      │  │  - config  │  │
│  └────────────┘  │                      │  └────────────┘  │
└─────────────────┘                      └─────────────────┘

Each machine runs a lightweight FastAPI relay server. Relays connect peer-to-peer via WebSocket. REST endpoints are localhost-only (no auth needed). The peer WebSocket authenticates with a shared secret.

How it works

1. CC session calls delegate_task("gpu-server", "run benchmarks", "...") via MCP
2. Local relay saves the task + message to SQLite, forwards to peer via WebSocket
3. Peer relay saves the task, notifies the connected CC session (or spawns a new claude process)
4. Peer CC works the task, responds via respond_to_task() or complete_task()
5. Response syncs back to the originator

Guards

• Delegation depth: Tasks can only be delegated once (depth 0 → 1). Prevents infinite loops.
• Spawn limit: Max 1 auto-spawned CC session at a time. Additional tasks queue.
• Message size: Content capped at 1MB.
• Offline sync: Messages queue locally when peer is disconnected, sync on reconnect.

Data storage

~/.distributed-coding-agent/
├── relay.db        # SQLite — tasks, messages, config
├── relay.pid       # Daemon PID file
├── mcp.log         # MCP server logs
└── .venv/          # Plugin's isolated Python environment

Development

pip install -e ".[dev]"
pytest -v