Peer System
LAN peer-to-peer — discover other Clew instances, send messages, delegate tasks, and execute commands remotely.
The peer system lives in src/peer/ and consists of three core layers: PeerServer (HTTP server), PeerDiscovery (LAN scanning), and PeerStore (in-memory registry).
Architecture
┌─────────────────────────────────────────────────────────────────────────────â”
│ PEER SYSTEM FLOW │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────â”
│ /peer share │
│ (Machine A — Worker) │
└────────────┬─────────────┘
│
┌─────────────────┼─────────────────â”
â–¼ â–¼ â–¼
┌──────────────┠┌──────────────┠┌──────────────â”
│ PeerServer │ │PeerDiscovery │ │ PeerStore │
│ HTTP :random │ │ │ │ (in-memory) │
│ port │ │ │ │ │
└──────┬───────┘ └──────┬───────┘ └──────────────┘
│ │
│ ┌────────────┼────────────â”
│ │ │ │
│ ▼ ▼ ▼
│ ┌────────┠┌────────┠┌─────────────â”
│ │ File │ │ UDP │ │ PeerStore │
│ │ ~/.cl/ │ │multicast│ │ (singleton) │
│ │ peers/ │ │239... │ │ │
│ │{pid}. │ │:42069 │ │ │
│ │ json │ │ │ │ │
│ └────┬───┘ └────┬───┘ └─────────────┘
│ │ │
│ │ │ heartbeat every 30s
│ │ │ stale timeout 90s
│ │ │
â–¼ â–¼ â–¼
┌─────────────────────────────────────────────────────â”
│ LAN NETWORK │
│ │
│ ┌─────────┠┌─────────┠│
│ │ Machine B│◄───────►│ Machine C│ ... │
│ │ Clew Code│ query │ Clew Code│ │
│ └────┬─────┘ └────┬─────┘ │
│ │ │ │
└────────┼────────────────────┼─────────────────────────┘
│ │
│ /peer discover │ /peer discover
â–¼ â–¼
â•â•â• WORKER (Machine A) ENDPOINTS â•â•â•
Peer à¸à¸·à¹ˆà¸™ POST /peer-info ──► { hostname, ip, cwd, shell, ... }
│ POST /peer-msg ──► receive chat message
├───────────────► POST /peer-todo ──► receive task (goes to inbox)
│ POST /peer-exec ──► run shell command + return stdout/stderr
â•â•â• CLIENT (Machine B) TOOLS â•â•â•
/peer discover ──► scan files + UDP query (3s timeout)
│
â–¼
[peer list]
│
┌───────────────────┼───────────────────â”
â–¼ â–¼ â–¼
/peer join /peer send_task /peer run
(POST /peer-info) (POST /peer-todo) (POST /peer-exec)
│
â–¼
/peer send_message ──► POST /peer-msg ──► destination inbox
/peer broadcast ──► POST /peer-msg ──► all connected peers
/peer ping ──► GET /peer-info ──► check alive
â•â•â• DAEMON (agentLoop.ts) â•â•â•
┌───────────────────────────────────â”
│ Autonomous Agent Loop │
│ - listens /peer-todo 24/7 │
│ - receives tasks from peers │
│ - executes in background worker │
│ - max 3 concurrent workers │
└───────────────────────────────────┘
â•â•â• DATA LIFECYCLE â•â•â•
advertise ──► heartbeat every 30s
│
├── 90s no heartbeat ──► stale → evict
│
stop share ──► send UDP "offline"
delete peer file
close HTTP serverCore Components
PeerServer src/peer/PeerServer.ts
Lightweight HTTP server started on a random OS-assigned port when /peer share is invoked. Each endpoint handles a different peer interaction:
| Endpoint | Method | Purpose |
|---|---|---|
/peer-info | GET | Return peer metadata (hostname, IP, cwd, shell, platform) |
/peer-msg | POST | Receive a chat message from another peer |
/peer-todo | POST | Receive a task delegation from another peer |
/peer-exec | POST | Execute a shell command and return stdout/stderr |
PeerDiscovery src/peer/PeerDiscovery.ts
Two discovery mechanisms work together:
- File-based — Each instance writes
~/.claude/peers/{pid}.jsonwith hostname, IP, port, shell, cwd. Other instances scan this directory to discover local peers. - UDP Multicast — Broadcasts heartbeat beacons to
239.255.37.37:42069every 30 seconds. Responds toclew-peer-querywithclew-peer-info. Cross-machine only. - Stale eviction — Peers unseen for 90 seconds (
PEER_STALE_TIMEOUT) are automatically removed.
PeerStore src/peer/PeerStore.ts
Singleton in-memory registry holding all known peers (discovered + explicitly joined), chat messages, todos, and custom tags (display names, roles).
- Discovered peers — Auto-evicted after stale timeout
- Joined connections — Persistent; never auto-cleaned
- Tags — Custom display names and roles per peer
Discovery Protocol
DiscoveryMessage =
| { type: "clew-peer-query", version: 1 } // broadcast scan
| { type: "clew-peer-info", version: 1, // heartbeat / response
id: string, hostname: string, ip: string, port: number,
cwd: string, sessionId?: string, appVersion: string,
shell?: string, platform?: string, term?: string,
status: "online" | "offline" }
UDP port: 42069
Multicast IP: 239.255.37.37
Heartbeat: every 30 seconds
Stale after: 90 secondsCommands
| Command | Description |
|---|---|
/peer | Open interactive peer menu (share, join, discover, inbox) |
/peer share | Start advertising this instance as a worker on the LAN |
/peer stop | Stop advertising and shut down the peer server |
/peer discover | Scan for available peers (file + UDP, 3s timeout) |
/peer join <host> <port> | Connect to a remote peer by host and port |
/peer name <name> | Set a custom display name for yourself |
/peer role <role> | Set a role label (builder, tester, deployer, etc.) |
/peer inbox | View pending messages and todos from peers |
/peer disconnect <peer> | Disconnect from a specific peer |
/peer todos | List all received tasks |
/peer todo done <id> | Mark a received task as done |
AI Tools
These are the tools the AI agent uses to interact with the peer system:
| Tool | Description |
|---|---|
peer_discover | Scan LAN for available Clew workers |
peer_join | Connect to a remote peer via HTTP |
peer_ping | Check if a peer is online (GET /peer-info) |
peer_info | Fetch detailed peer information |
peer_send_message | Send a chat message to a peer |
peer_send_task | Assign a task to a remote worker |
peer_broadcast | Send a task to all connected peers simultaneously |
peer_run | Execute a shell command on a remote worker |
peer_disconnect | Remove a peer from the connection list |
peer_list_messages | List all received chat messages |
peer_list_roles | List all peers with their roles |
peer_list_tasks | List all task assignments and their status |
peer_set_name | Assign a custom display name to a peer |
peer_set_role | Assign a functional role to a peer |
peer_share | Toggle sharing (start/stop/status) |
DAEMON Integration
The autonomous agent loop (src/services/autonomous/agentLoop.ts) integrates with PeerServer to accept tasks from remote peers:
- Listens for incoming
/peer-todoPOSTs 24/7 - Queues received tasks and processes them in background workers
- Max 3 concurrent workers; tasks time out after 30 minutes
- Results are available via
/peer todosand/tasks
Architecture Files
| File | Role |
|---|---|
src/peer/PeerServer.ts | HTTP server with /peer-info, /peer-msg, /peer-todo, /peer-exec endpoints |
src/peer/PeerDiscovery.ts | File-based + UDP multicast LAN peer discovery |
src/peer/PeerStore.ts | In-memory singleton registry (peers, messages, todos, tags) |
src/peer/types.ts | Shared types and protocol constants |
src/commands/peer/ | Interactive peer menu and CLI commands |
src/tools/Peer*Tool/ | 16 AI agent tools wrapping peer operations |
src/services/autonomous/agentLoop.ts | Daemon integration: accepts remote tasks via PeerServer |