clew-code 0.2.7 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +292 -299
  2. package/dist/main.js +2745 -2869
  3. package/docs/architecture.html +148 -145
  4. package/docs/architecture.th.html +79 -78
  5. package/docs/clew-code-architecture.html +1125 -0
  6. package/docs/commands.html +224 -223
  7. package/docs/commands.th.html +131 -130
  8. package/docs/configuration.html +147 -145
  9. package/docs/configuration.th.html +108 -106
  10. package/docs/css/styles.css +48 -42
  11. package/docs/daemon.html +129 -128
  12. package/docs/daemon.th.html +73 -72
  13. package/docs/features/bridge-mode.html +99 -98
  14. package/docs/features/bridge-mode.th.html +90 -89
  15. package/docs/features/evals.html +182 -181
  16. package/docs/features/evals.th.html +90 -89
  17. package/docs/features/peer.html +178 -177
  18. package/docs/features/searxng-search.html +151 -150
  19. package/docs/features/searxng-search.th.html +95 -94
  20. package/docs/features/sentry-setup.html +157 -156
  21. package/docs/features/sentry-setup.th.html +97 -96
  22. package/docs/index.html +299 -298
  23. package/docs/index.th.html +292 -290
  24. package/docs/installation.html +105 -103
  25. package/docs/installation.th.html +105 -103
  26. package/docs/internals/growthbook-ab-testing.html +113 -112
  27. package/docs/internals/growthbook-ab-testing.th.html +81 -80
  28. package/docs/internals/hidden-features.html +149 -147
  29. package/docs/internals/hidden-features.th.html +109 -107
  30. package/docs/js/main.js +83 -3
  31. package/docs/loop.html +181 -180
  32. package/docs/loop.th.html +227 -226
  33. package/docs/mcp.html +247 -246
  34. package/docs/mcp.th.html +207 -206
  35. package/docs/models.html +111 -110
  36. package/docs/models.th.html +61 -60
  37. package/docs/peer.html +236 -235
  38. package/docs/peer.th.html +280 -279
  39. package/docs/permission-model.html +102 -101
  40. package/docs/permission-model.th.html +67 -66
  41. package/docs/plugins.html +102 -101
  42. package/docs/plugins.th.html +79 -78
  43. package/docs/providers.html +126 -117
  44. package/docs/providers.th.html +80 -78
  45. package/docs/quick-start.html +93 -92
  46. package/docs/quick-start.th.html +40 -39
  47. package/docs/research-memory.html +82 -79
  48. package/docs/research-memory.th.html +72 -71
  49. package/docs/skills.html +117 -116
  50. package/docs/skills.th.html +90 -89
  51. package/docs/tools.html +170 -169
  52. package/docs/tools.th.html +84 -83
  53. package/docs/troubleshooting.html +106 -105
  54. package/docs/troubleshooting.th.html +85 -84
  55. package/package.json +164 -162
  56. package/docs/taste.html +0 -436
  57. package/docs/taste.th.html +0 -236
package/docs/peer.html CHANGED
@@ -1,235 +1,236 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>Peer System — Clew</title>
7
- <meta name="description" content="LAN peer-to-peer system — discovery, messaging, task delegation, and remote execution between Clew instances.">
8
- <link rel="preconnect" href="https://fonts.googleapis.com">
9
- <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
- <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
11
- <link rel="stylesheet" href="css/styles.css">
12
- <link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
13
- </head>
14
- <body>
15
- <header class="header"></header>
16
- <div class="app">
17
- <aside class="sidebar" id="sidebar"></aside>
18
- <div class="sidebar-overlay" id="sidebarOverlay"></div>
19
- <div class="content-wrap">
20
- <main class="content">
21
- <div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Peer System</span></div>
22
- <h1>Peer System</h1>
23
- <p class="section-subtitle">LAN peer-to-peer — discover other Clew instances, send messages, delegate tasks, and execute commands remotely.</p>
24
-
25
- <p>The peer system lives in <code>src/peer/</code> and consists of three core layers: <strong>PeerServer</strong> (HTTP server), <strong>PeerDiscovery</strong> (LAN scanning), and <strong>PeerStore</strong> (in-memory registry).</p>
26
-
27
- <h2>Architecture</h2>
28
- <pre><code> ┌─────────────────────────────────────────────────────────────────────────────┐
29
- │ PEER SYSTEM FLOW │
30
- └─────────────────────────────────────────────────────────────────────────────┘
31
-
32
- ┌──────────────────────────┐
33
- │ /peer share │
34
- │ (Machine A — Worker) │
35
- └────────────┬─────────────┘
36
- │
37
- ┌─────────────────┼─────────────────┐
38
- ▼ ▼ ▼
39
- ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
40
- │ PeerServer │ │PeerDiscovery │ │ PeerStore │
41
- │ HTTP :random │ │ │ │ (in-memory) │
42
- │ port │ │ │ │ │
43
- └──────┬───────┘ └──────┬───────┘ └──────────────┘
44
- │ │
45
- │ ┌────────────┼────────────┐
46
- │ │ │ │
47
- │ ▼ ▼ ▼
48
- │ ┌────────┐ ┌────────┐ ┌─────────────┐
49
- │ │ File │ │ UDP │ │ PeerStore │
50
- │ │ ~/.cl/ │ │multicast│ │ (singleton) │
51
- │ │ peers/ │ │239... │ │ │
52
- │ │{pid}. │ │:42069 │ │ │
53
- │ │ json │ │ │ │ │
54
- │ └────┬───┘ └────┬───┘ └─────────────┘
55
- │ │ │
56
- │ │ │ heartbeat every 30s
57
- │ │ │ stale timeout 90s
58
- │ │ │
59
- ▼ ▼ ▼
60
- ┌─────────────────────────────────────────────────────┐
61
- │ LAN NETWORK │
62
- │ │
63
- │ ┌─────────┐ ┌─────────┐ │
64
- │ │ Machine B│◄───────►│ Machine C│ ... │
65
- │ │ Clew Code│ query │ Clew Code│ │
66
- │ └────┬─────┘ └────┬─────┘ │
67
- │ │ │ │
68
- └────────┼────────────────────┼─────────────────────────┘
69
- │ │
70
- │ /peer discover │ /peer discover
71
- ▼ ▼
72
-
73
-
74
- ═══ WORKER (Machine A) ENDPOINTS ═══
75
-
76
- Peer อื่น POST /peer-info ──► { hostname, ip, cwd, shell, ... }
77
- │ POST /peer-msg ──► receive chat message
78
- ├───────────────► POST /peer-todo ──► receive task (goes to inbox)
79
- │ POST /peer-exec ──► run shell command + return stdout/stderr
80
-
81
-
82
- ═══ CLIENT (Machine B) TOOLS ═══
83
-
84
- /peer discover ──► scan files + UDP query (3s timeout)
85
- │
86
- ▼
87
- [peer list]
88
- │
89
- ┌───────────────────┼───────────────────┐
90
- ▼ ▼ ▼
91
- /peer join /peer send_task /peer run
92
- (POST /peer-info) (POST /peer-todo) (POST /peer-exec)
93
-
94
- │
95
- ▼
96
- /peer send_message ──► POST /peer-msg ──► destination inbox
97
- /peer broadcast ──► POST /peer-msg ──► all connected peers
98
- /peer ping ──► GET /peer-info ──► check alive
99
-
100
-
101
- ═══ DAEMON (agentLoop.ts) ═══
102
-
103
- ┌───────────────────────────────────┐
104
- │ Autonomous Agent Loop │
105
- │ - listens /peer-todo 24/7 │
106
- │ - receives tasks from peers │
107
- │ - executes in background worker │
108
- │ - max 3 concurrent workers │
109
- └───────────────────────────────────┘
110
-
111
-
112
- ═══ DATA LIFECYCLE ═══
113
-
114
- advertise ──► heartbeat every 30s
115
- │
116
- ├── 90s no heartbeat ──► stale → evict
117
- │
118
- stop share ──► send UDP "offline"
119
- delete peer file
120
- close HTTP server</code></pre>
121
-
122
- <h2>Core Components</h2>
123
-
124
- <h3>PeerServer <code>src/peer/PeerServer.ts</code></h3>
125
- <p>Lightweight HTTP server started on a random OS-assigned port when <code>/peer share</code> is invoked. Each endpoint handles a different peer interaction:</p>
126
- <table>
127
- <tr><th>Endpoint</th><th>Method</th><th>Purpose</th></tr>
128
- <tr><td><code>/peer-info</code></td><td>GET</td><td>Return peer metadata (hostname, IP, cwd, shell, platform)</td></tr>
129
- <tr><td><code>/peer-msg</code></td><td>POST</td><td>Receive a chat message from another peer</td></tr>
130
- <tr><td><code>/peer-todo</code></td><td>POST</td><td>Receive a task delegation from another peer</td></tr>
131
- <tr><td><code>/peer-exec</code></td><td>POST</td><td>Execute a shell command and return stdout/stderr</td></tr>
132
- </table>
133
-
134
- <h3>PeerDiscovery <code>src/peer/PeerDiscovery.ts</code></h3>
135
- <p>Two discovery mechanisms work together:</p>
136
- <ul>
137
- <li><strong>File-based</strong> — Each instance writes <code>~/.claude/peers/{pid}.json</code> with hostname, IP, port, shell, cwd. Other instances scan this directory to discover local peers.</li>
138
- <li><strong>UDP Multicast</strong> — Broadcasts heartbeat beacons to <code>239.255.37.37:42069</code> every 30 seconds. Responds to <code>clew-peer-query</code> with <code>clew-peer-info</code>. Cross-machine only.</li>
139
- <li><strong>Stale eviction</strong> — Peers unseen for 90 seconds (<code>PEER_STALE_TIMEOUT</code>) are automatically removed.</li>
140
- </ul>
141
-
142
- <h3>PeerStore <code>src/peer/PeerStore.ts</code></h3>
143
- <p>Singleton in-memory registry holding all known peers (discovered + explicitly joined), chat messages, todos, and custom tags (display names, roles).</p>
144
- <ul>
145
- <li><strong>Discovered peers</strong> — Auto-evicted after stale timeout</li>
146
- <li><strong>Joined connections</strong> — Persistent; never auto-cleaned</li>
147
- <li><strong>Tags</strong> — Custom display names and roles per peer</li>
148
- </ul>
149
-
150
- <h2>Discovery Protocol</h2>
151
- <pre><code>DiscoveryMessage =
152
- | { type: "clew-peer-query", version: 1 } // broadcast scan
153
- | { type: "clew-peer-info", version: 1, // heartbeat / response
154
- id: string, hostname: string, ip: string, port: number,
155
- cwd: string, sessionId?: string, appVersion: string,
156
- shell?: string, platform?: string, term?: string,
157
- status: "online" | "offline" }
158
-
159
- UDP port: 42069
160
- Multicast IP: 239.255.37.37
161
- Heartbeat: every 30 seconds
162
- Stale after: 90 seconds</code></pre>
163
-
164
- <h2>Commands</h2>
165
- <table>
166
- <tr><th>Command</th><th>Description</th></tr>
167
- <tr><td><code>/peer</code></td><td>Open interactive peer menu (share, join, discover, inbox)</td></tr>
168
- <tr><td><code>/peer share</code></td><td>Start advertising this instance as a worker on the LAN</td></tr>
169
- <tr><td><code>/peer stop</code></td><td>Stop advertising and shut down the peer server</td></tr>
170
- <tr><td><code>/peer discover</code></td><td>Scan for available peers (file + UDP, 3s timeout)</td></tr>
171
- <tr><td><code>/peer join &lt;host&gt; &lt;port&gt;</code></td><td>Connect to a remote peer by host and port</td></tr>
172
- <tr><td><code>/peer name &lt;name&gt;</code></td><td>Set a custom display name for yourself</td></tr>
173
- <tr><td><code>/peer role &lt;role&gt;</code></td><td>Set a role label (builder, tester, deployer, etc.)</td></tr>
174
- <tr><td><code>/peer inbox</code></td><td>View pending messages and todos from peers</td></tr>
175
- <tr><td><code>/peer disconnect &lt;peer&gt;</code></td><td>Disconnect from a specific peer</td></tr>
176
- <tr><td><code>/peer todos</code></td><td>List all received tasks</td></tr>
177
- <tr><td><code>/peer todo done &lt;id&gt;</code></td><td>Mark a received task as done</td></tr>
178
- </table>
179
-
180
- <h2>AI Tools</h2>
181
- <p>These are the tools the AI agent uses to interact with the peer system:</p>
182
- <table>
183
- <tr><th>Tool</th><th>Description</th></tr>
184
- <tr><td><code>peer_discover</code></td><td>Scan LAN for available Clew workers</td></tr>
185
- <tr><td><code>peer_join</code></td><td>Connect to a remote peer via HTTP</td></tr>
186
- <tr><td><code>peer_ping</code></td><td>Check if a peer is online (GET /peer-info)</td></tr>
187
- <tr><td><code>peer_info</code></td><td>Fetch detailed peer information</td></tr>
188
- <tr><td><code>peer_send_message</code></td><td>Send a chat message to a peer</td></tr>
189
- <tr><td><code>peer_send_task</code></td><td>Assign a task to a remote worker</td></tr>
190
- <tr><td><code>peer_broadcast</code></td><td>Send a task to all connected peers simultaneously</td></tr>
191
- <tr><td><code>peer_run</code></td><td>Execute a shell command on a remote worker</td></tr>
192
- <tr><td><code>peer_disconnect</code></td><td>Remove a peer from the connection list</td></tr>
193
- <tr><td><code>peer_list_messages</code></td><td>List all received chat messages</td></tr>
194
- <tr><td><code>peer_list_roles</code></td><td>List all peers with their roles</td></tr>
195
- <tr><td><code>peer_list_tasks</code></td><td>List all task assignments and their status</td></tr>
196
- <tr><td><code>peer_set_name</code></td><td>Assign a custom display name to a peer</td></tr>
197
- <tr><td><code>peer_set_role</code></td><td>Assign a functional role to a peer</td></tr>
198
- <tr><td><code>peer_share</code></td><td>Toggle sharing (start/stop/status)</td></tr>
199
- </table>
200
-
201
- <h2>DAEMON Integration</h2>
202
- <p>The autonomous agent loop (<code>src/services/autonomous/agentLoop.ts</code>) integrates with PeerServer to accept tasks from remote peers:</p>
203
- <ul>
204
- <li>Listens for incoming <code>/peer-todo</code> POSTs 24/7</li>
205
- <li>Queues received tasks and processes them in background workers</li>
206
- <li>Max 3 concurrent workers; tasks time out after 30 minutes</li>
207
- <li>Results are available via <code>/peer todos</code> and <code>/tasks</code></li>
208
- </ul>
209
-
210
- <h2>Architecture Files</h2>
211
- <table>
212
- <tr><th>File</th><th>Role</th></tr>
213
- <tr><td><code>src/peer/PeerServer.ts</code></td><td>HTTP server with /peer-info, /peer-msg, /peer-todo, /peer-exec endpoints</td></tr>
214
- <tr><td><code>src/peer/PeerDiscovery.ts</code></td><td>File-based + UDP multicast LAN peer discovery</td></tr>
215
- <tr><td><code>src/peer/PeerStore.ts</code></td><td>In-memory singleton registry (peers, messages, todos, tags)</td></tr>
216
- <tr><td><code>src/peer/types.ts</code></td><td>Shared types and protocol constants</td></tr>
217
- <tr><td><code>src/commands/peer/</code></td><td>Interactive peer menu and CLI commands</td></tr>
218
- <tr><td><code>src/tools/Peer*Tool/</code></td><td>16 AI agent tools wrapping peer operations</td></tr>
219
- <tr><td><code>src/services/autonomous/agentLoop.ts</code></td><td>Daemon integration: accepts remote tasks via PeerServer</td></tr>
220
- </table>
221
-
222
- <footer class="footer">
223
- <span>Clew Code v0.2.4 — Open Source</span>
224
- <div class="footer-links">
225
- <a href="https://github.com/JonusNattapong/ClewCode">GitHub</a>
226
- <a href="https://github.com/JonusNattapong/ClewCode/issues">Issues</a>
227
- </div>
228
- </footer>
229
- </main>
230
- <nav class="toc-sidebar"></nav>
231
- </div>
232
- </div>
233
- <script src="js/main.js"></script>
234
- </body>
235
- </html>
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Peer System — Clew</title>
7
+ <meta name="description" content="LAN peer-to-peer system — discovery, messaging, task delegation, and remote execution between Clew instances.">
8
+ <link rel="preconnect" href="https://fonts.googleapis.com">
9
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
11
+ <link rel="stylesheet" href="css/styles.css">
12
+ <link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
13
+ </head>
14
+ <body>
15
+ <header class="header"></header>
16
+ <div class="app">
17
+ <aside class="sidebar" id="sidebar"></aside>
18
+ <div class="sidebar-overlay" id="sidebarOverlay"></div>
19
+ <div class="content-wrap">
20
+ <main class="content">
21
+ <div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Peer System</span></div>
22
+ <h1>Peer System</h1>
23
+ <p class="section-subtitle">LAN peer-to-peer — discover other Clew instances, send messages, delegate tasks, and execute commands remotely.</p>
24
+
25
+ <p>The peer system lives in <code>src/peer/</code> and consists of three core layers: <strong>PeerServer</strong> (HTTP server), <strong>PeerDiscovery</strong> (LAN scanning), and <strong>PeerStore</strong> (in-memory registry).</p>
26
+
27
+ <h2>Architecture</h2>
28
+ <pre><code> ┌─────────────────────────────────────────────────────────────────────────────┐
29
+ │ PEER SYSTEM FLOW │
30
+ └─────────────────────────────────────────────────────────────────────────────┘
31
+
32
+ ┌──────────────────────────┐
33
+ │ /peer share │
34
+ │ (Machine A — Worker) │
35
+ └────────────┬─────────────┘
36
+ │
37
+ ┌─────────────────┼─────────────────┐
38
+ â–¼ â–¼ â–¼
39
+ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
40
+ │ PeerServer │ │PeerDiscovery │ │ PeerStore │
41
+ │ HTTP :random │ │ │ │ (in-memory) │
42
+ │ port │ │ │ │ │
43
+ └──────┬───────┘ └──────┬───────┘ └──────────────┘
44
+ │ │
45
+ │ ┌────────────┼────────────┐
46
+ │ │ │ │
47
+ │ ▼ ▼ ▼
48
+ │ ┌────────┐ ┌────────┐ ┌─────────────┐
49
+ │ │ File │ │ UDP │ │ PeerStore │
50
+ │ │ ~/.cl/ │ │multicast│ │ (singleton) │
51
+ │ │ peers/ │ │239... │ │ │
52
+ │ │{pid}. │ │:42069 │ │ │
53
+ │ │ json │ │ │ │ │
54
+ │ └────┬───┘ └────┬───┘ └─────────────┘
55
+ │ │ │
56
+ │ │ │ heartbeat every 30s
57
+ │ │ │ stale timeout 90s
58
+ │ │ │
59
+ â–¼ â–¼ â–¼
60
+ ┌─────────────────────────────────────────────────────┐
61
+ │ LAN NETWORK │
62
+ │ │
63
+ │ ┌─────────┐ ┌─────────┐ │
64
+ │ │ Machine B│◄───────►│ Machine C│ ... │
65
+ │ │ Clew Code│ query │ Clew Code│ │
66
+ │ └────┬─────┘ └────┬─────┘ │
67
+ │ │ │ │
68
+ └────────┼────────────────────┼─────────────────────────┘
69
+ │ │
70
+ │ /peer discover │ /peer discover
71
+ â–¼ â–¼
72
+
73
+
74
+ ═══ WORKER (Machine A) ENDPOINTS ═══
75
+
76
+ Peer อื่น POST /peer-info ──► { hostname, ip, cwd, shell, ... }
77
+ │ POST /peer-msg ──► receive chat message
78
+ ├───────────────► POST /peer-todo ──► receive task (goes to inbox)
79
+ │ POST /peer-exec ──► run shell command + return stdout/stderr
80
+
81
+
82
+ ═══ CLIENT (Machine B) TOOLS ═══
83
+
84
+ /peer discover ──► scan files + UDP query (3s timeout)
85
+ │
86
+ â–¼
87
+ [peer list]
88
+ │
89
+ ┌───────────────────┼───────────────────┐
90
+ â–¼ â–¼ â–¼
91
+ /peer join /peer send_task /peer run
92
+ (POST /peer-info) (POST /peer-todo) (POST /peer-exec)
93
+
94
+ │
95
+ â–¼
96
+ /peer send_message ──► POST /peer-msg ──► destination inbox
97
+ /peer broadcast ──► POST /peer-msg ──► all connected peers
98
+ /peer ping ──► GET /peer-info ──► check alive
99
+
100
+
101
+ ═══ DAEMON (agentLoop.ts) ═══
102
+
103
+ ┌───────────────────────────────────┐
104
+ │ Autonomous Agent Loop │
105
+ │ - listens /peer-todo 24/7 │
106
+ │ - receives tasks from peers │
107
+ │ - executes in background worker │
108
+ │ - max 3 concurrent workers │
109
+ └───────────────────────────────────┘
110
+
111
+
112
+ ═══ DATA LIFECYCLE ═══
113
+
114
+ advertise ──► heartbeat every 30s
115
+ │
116
+ ├── 90s no heartbeat ──► stale → evict
117
+ │
118
+ stop share ──► send UDP "offline"
119
+ delete peer file
120
+ close HTTP server</code></pre>
121
+
122
+ <h2>Core Components</h2>
123
+
124
+ <h3>PeerServer <code>src/peer/PeerServer.ts</code></h3>
125
+ <p>Lightweight HTTP server started on a random OS-assigned port when <code>/peer share</code> is invoked. Each endpoint handles a different peer interaction:</p>
126
+ <table>
127
+ <tr><th>Endpoint</th><th>Method</th><th>Purpose</th></tr>
128
+ <tr><td><code>/peer-info</code></td><td>GET</td><td>Return peer metadata (hostname, IP, cwd, shell, platform)</td></tr>
129
+ <tr><td><code>/peer-msg</code></td><td>POST</td><td>Receive a chat message from another peer</td></tr>
130
+ <tr><td><code>/peer-todo</code></td><td>POST</td><td>Receive a task delegation from another peer</td></tr>
131
+ <tr><td><code>/peer-exec</code></td><td>POST</td><td>Execute a shell command and return stdout/stderr</td></tr>
132
+ </table>
133
+
134
+ <h3>PeerDiscovery <code>src/peer/PeerDiscovery.ts</code></h3>
135
+ <p>Two discovery mechanisms work together:</p>
136
+ <ul>
137
+ <li><strong>File-based</strong> — Each instance writes <code>~/.claude/peers/{pid}.json</code> with hostname, IP, port, shell, cwd. Other instances scan this directory to discover local peers.</li>
138
+ <li><strong>UDP Multicast</strong> — Broadcasts heartbeat beacons to <code>239.255.37.37:42069</code> every 30 seconds. Responds to <code>clew-peer-query</code> with <code>clew-peer-info</code>. Cross-machine only.</li>
139
+ <li><strong>Stale eviction</strong> — Peers unseen for 90 seconds (<code>PEER_STALE_TIMEOUT</code>) are automatically removed.</li>
140
+ </ul>
141
+
142
+ <h3>PeerStore <code>src/peer/PeerStore.ts</code></h3>
143
+ <p>Singleton in-memory registry holding all known peers (discovered + explicitly joined), chat messages, todos, and custom tags (display names, roles).</p>
144
+ <ul>
145
+ <li><strong>Discovered peers</strong> — Auto-evicted after stale timeout</li>
146
+ <li><strong>Joined connections</strong> — Persistent; never auto-cleaned</li>
147
+ <li><strong>Tags</strong> — Custom display names and roles per peer</li>
148
+ </ul>
149
+
150
+ <h2>Discovery Protocol</h2>
151
+ <pre><code>DiscoveryMessage =
152
+ | { type: "clew-peer-query", version: 1 } // broadcast scan
153
+ | { type: "clew-peer-info", version: 1, // heartbeat / response
154
+ id: string, hostname: string, ip: string, port: number,
155
+ cwd: string, sessionId?: string, appVersion: string,
156
+ shell?: string, platform?: string, term?: string,
157
+ status: "online" | "offline" }
158
+
159
+ UDP port: 42069
160
+ Multicast IP: 239.255.37.37
161
+ Heartbeat: every 30 seconds
162
+ Stale after: 90 seconds</code></pre>
163
+
164
+ <h2>Commands</h2>
165
+ <table>
166
+ <tr><th>Command</th><th>Description</th></tr>
167
+ <tr><td><code>/peer</code></td><td>Open interactive peer menu (share, join, discover, inbox)</td></tr>
168
+ <tr><td><code>/peer share</code></td><td>Start advertising this instance as a worker on the LAN</td></tr>
169
+ <tr><td><code>/peer stop</code></td><td>Stop advertising and shut down the peer server</td></tr>
170
+ <tr><td><code>/peer discover</code></td><td>Scan for available peers (file + UDP, 3s timeout)</td></tr>
171
+ <tr><td><code>/peer join &lt;host&gt; &lt;port&gt;</code></td><td>Connect to a remote peer by host and port</td></tr>
172
+ <tr><td><code>/peer name &lt;name&gt;</code></td><td>Set a custom display name for yourself</td></tr>
173
+ <tr><td><code>/peer role &lt;role&gt;</code></td><td>Set a role label (builder, tester, deployer, etc.)</td></tr>
174
+ <tr><td><code>/peer inbox</code></td><td>View pending messages and todos from peers</td></tr>
175
+ <tr><td><code>/peer disconnect &lt;peer&gt;</code></td><td>Disconnect from a specific peer</td></tr>
176
+ <tr><td><code>/peer todos</code></td><td>List all received tasks</td></tr>
177
+ <tr><td><code>/peer todo done &lt;id&gt;</code></td><td>Mark a received task as done</td></tr>
178
+ </table>
179
+
180
+ <h2>AI Tools</h2>
181
+ <p>These are the tools the AI agent uses to interact with the peer system:</p>
182
+ <table>
183
+ <tr><th>Tool</th><th>Description</th></tr>
184
+ <tr><td><code>peer_discover</code></td><td>Scan LAN for available Clew workers</td></tr>
185
+ <tr><td><code>peer_join</code></td><td>Connect to a remote peer via HTTP</td></tr>
186
+ <tr><td><code>peer_ping</code></td><td>Check if a peer is online (GET /peer-info)</td></tr>
187
+ <tr><td><code>peer_info</code></td><td>Fetch detailed peer information</td></tr>
188
+ <tr><td><code>peer_send_message</code></td><td>Send a chat message to a peer</td></tr>
189
+ <tr><td><code>peer_send_task</code></td><td>Assign a task to a remote worker</td></tr>
190
+ <tr><td><code>peer_broadcast</code></td><td>Send a task to all connected peers simultaneously</td></tr>
191
+ <tr><td><code>peer_run</code></td><td>Execute a shell command on a remote worker</td></tr>
192
+ <tr><td><code>peer_disconnect</code></td><td>Remove a peer from the connection list</td></tr>
193
+ <tr><td><code>peer_list_messages</code></td><td>List all received chat messages</td></tr>
194
+ <tr><td><code>peer_list_roles</code></td><td>List all peers with their roles</td></tr>
195
+ <tr><td><code>peer_list_tasks</code></td><td>List all task assignments and their status</td></tr>
196
+ <tr><td><code>peer_set_name</code></td><td>Assign a custom display name to a peer</td></tr>
197
+ <tr><td><code>peer_set_role</code></td><td>Assign a functional role to a peer</td></tr>
198
+ <tr><td><code>peer_share</code></td><td>Toggle sharing (start/stop/status)</td></tr>
199
+ </table>
200
+
201
+ <h2>DAEMON Integration</h2>
202
+ <p>The autonomous agent loop (<code>src/services/autonomous/agentLoop.ts</code>) integrates with PeerServer to accept tasks from remote peers:</p>
203
+ <ul>
204
+ <li>Listens for incoming <code>/peer-todo</code> POSTs 24/7</li>
205
+ <li>Queues received tasks and processes them in background workers</li>
206
+ <li>Max 3 concurrent workers; tasks time out after 30 minutes</li>
207
+ <li>Results are available via <code>/peer todos</code> and <code>/tasks</code></li>
208
+ </ul>
209
+
210
+ <h2>Architecture Files</h2>
211
+ <table>
212
+ <tr><th>File</th><th>Role</th></tr>
213
+ <tr><td><code>src/peer/PeerServer.ts</code></td><td>HTTP server with /peer-info, /peer-msg, /peer-todo, /peer-exec endpoints</td></tr>
214
+ <tr><td><code>src/peer/PeerDiscovery.ts</code></td><td>File-based + UDP multicast LAN peer discovery</td></tr>
215
+ <tr><td><code>src/peer/PeerStore.ts</code></td><td>In-memory singleton registry (peers, messages, todos, tags)</td></tr>
216
+ <tr><td><code>src/peer/types.ts</code></td><td>Shared types and protocol constants</td></tr>
217
+ <tr><td><code>src/commands/peer/</code></td><td>Interactive peer menu and CLI commands</td></tr>
218
+ <tr><td><code>src/tools/Peer*Tool/</code></td><td>16 AI agent tools wrapping peer operations</td></tr>
219
+ <tr><td><code>src/services/autonomous/agentLoop.ts</code></td><td>Daemon integration: accepts remote tasks via PeerServer</td></tr>
220
+ </table>
221
+
222
+ <footer class="footer">
223
+ <span>Clew Code v0.2.7 — Open Source</span>
224
+ <div class="footer-links">
225
+ <a href="https://github.com/ClewCode/ClewCode">GitHub</a>
226
+ <a href="https://github.com/ClewCode/ClewCode/issues">Issues</a>
227
+ </div>
228
+ </footer>
229
+ </main>
230
+ <nav class="toc-sidebar"></nav>
231
+ </div>
232
+ </div>
233
+ <script src="js/main.js"></script>
234
+ </body>
235
+ </html>
236
+