Home â€º Peer-to-Peer

Peer-to-Peer Collaboration

Clew supports LAN peer discovery and task delegation, enabling a lead-worker model where one instance can coordinate multiple worker instances on the same network.

Architecture

Each peer runs a lightweight HTTP server (PeerServer) on a random port. Discovery uses UDP multicast broadcast (239.255.37.37:42069) plus a file-based registry (~/.claude/peers/) for same-machine peers.

Peer A (Lead)                    Peer B (Worker)
  |                                |
  |--- UDP multicast query ------->|
  |<--- response (host, port, cwd)-|
  |                                |
  |--- HTTP POST /peer-todo ------>|  Assign task
  |--- HTTP POST /peer-exec ------>|  Run command
  |<--- response ------------------|  Return result

Getting Started

Worker Setup

# Start sharing (advertise on LAN)
/peer share

# Set display name and role
/peer name Build Server
/peer role builder

Lead Setup

# Discover available peers
/peer discover

# Join a specific peer by port
/peer join 127.0.0.1:59421

# View connected peers
/peer list

Assign Tasks

# Direct task assignment
/peer todo Build-Server "run the test suite"

# Let the AI handle it
> Assign a task to the build server to run all tests

Commands

Command	Description
`/peer`	Open interactive peer menu
`/peer share`	Start advertising as a worker
`/peer share stop`	Stop advertising
`/peer discover`	Scan LAN for peers (5s timeout)
`/peer join <port>`	Connect to a peer by port or host:port
`/peer list`	Open interactive peer list
`/peer todo <peer> <task>`	Assign a task to a worker
`/peer todos`	View received tasks
`/peer todo done <id>`	Mark task as complete
`/peer name <name>`	Set your display name
`/peer role <role>`	Set your role (e.g., builder, tester)
`/peer inbox`	View pending messages
`/peer spawn [options]`	Spawn a new peer shell terminal
`/peer help`	Show help

AI Peer Tools

Clew AI can autonomously coordinate peers using these tools:

Tool	Description
`peer_discover`	Scan for workers on LAN and same machine
`peer_join`	Connect to a remote peer by host:port
`peer_send_task`	Assign a task to a worker via HTTP POST
`peer_list_tasks`	Check pending and completed tasks
`peer_list_roles`	List all peers with names, roles, and IPs
`peer_run`	Execute a shell command on a remote worker
`peer_share`	Start or stop advertising as a worker
`peer_info`	Get detailed info about a specific peer
`peer_set_name`	Set display name for a peer
`peer_set_role`	Set role for a peer

Protocol

Discovery uses UDP multicast on 239.255.37.37:42069. Peer info is broadcast every 30 seconds. Peers are evicted after 90 seconds of inactivity.

Communication uses HTTP POST to registered peer endpoints:

Endpoint	Method	Description
`/peer-info`	GET	Get peer metadata (host, port, cwd, name, role)
`/peer-todo`	POST	Accept inbound task assignment
`/peer-msg`	POST	Accept inbound message
`/peer-exec`	POST	Accept shell command execution