# 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