clew-code 0.2.20 → 0.2.22
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.
- package/dist/main.js +1888 -1883
- package/docs/architecture.html +91 -148
- package/docs/assets/clew-agent-loop.png +0 -0
- package/docs/assets/clew-general-architecture.png +0 -0
- package/docs/assets/clew-mcp-architecture.png +0 -0
- package/docs/assets/clew-p2p-swarm.png +0 -0
- package/docs/changelog.html +150 -0
- package/docs/cli-reference.html +90 -0
- package/docs/commands.html +156 -265
- package/docs/configuration.html +85 -147
- package/docs/contributing.html +91 -0
- package/docs/css/styles.css +425 -425
- package/docs/daemon.html +62 -129
- package/docs/features/bridge-mode.html +61 -66
- package/docs/features/evals.html +57 -149
- package/docs/features/searxng-search.html +58 -118
- package/docs/features/sentry-setup.html +61 -124
- package/docs/index.html +137 -125
- package/docs/installation.html +77 -105
- package/docs/internals/growthbook-ab-testing.html +69 -91
- package/docs/internals/hidden-features.html +81 -143
- package/docs/js/main.js +29 -0
- package/docs/loop.html +69 -181
- package/docs/mcp.html +99 -247
- package/docs/models.html +69 -110
- package/docs/permission-model.html +86 -102
- package/docs/plugins.html +84 -102
- package/docs/providers.html +87 -127
- package/docs/quick-start.html +81 -93
- package/docs/research-memory.html +71 -102
- package/docs/security.html +71 -0
- package/docs/skills.html +67 -117
- package/docs/swarm.html +78 -236
- package/docs/tools.html +152 -151
- package/docs/troubleshooting.html +86 -106
- package/docs/voice-mode.html +79 -0
- package/package.json +1 -1
- package/docs/architecture.th.html +0 -79
- package/docs/clew-code-architecture.html +0 -1126
- package/docs/commands.th.html +0 -269
- package/docs/configuration.th.html +0 -108
- package/docs/daemon.th.html +0 -73
- package/docs/features/bridge-mode.th.html +0 -62
- package/docs/features/evals.th.html +0 -62
- package/docs/features/searxng-search.th.html +0 -67
- package/docs/features/sentry-setup.th.html +0 -69
- package/docs/features/swarm.html +0 -156
- package/docs/generated/providers.html +0 -625
- package/docs/generated/tools.html +0 -558
- package/docs/index.th.html +0 -292
- package/docs/installation.th.html +0 -105
- package/docs/internals/growthbook-ab-testing.th.html +0 -60
- package/docs/internals/hidden-features.th.html +0 -107
- package/docs/loop.th.html +0 -227
- package/docs/mcp.th.html +0 -207
- package/docs/models.th.html +0 -61
- package/docs/permission-model.th.html +0 -67
- package/docs/plugins.th.html +0 -79
- package/docs/prompts-and-features.html +0 -806
- package/docs/providers.th.html +0 -81
- package/docs/quick-start.th.html +0 -89
- package/docs/research-memory.th.html +0 -72
- package/docs/skills.th.html +0 -90
- package/docs/swarm.th.html +0 -280
- package/docs/tools.th.html +0 -84
- package/docs/troubleshooting.th.html +0 -85
|
@@ -0,0 +1,71 @@
|
|
|
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>Security — Clew Code</title>
|
|
7
|
+
<meta name="description" content="Security model, license, and responsible disclosure for Clew Code.">
|
|
8
|
+
<link rel="icon" type="image/svg+xml" href="assets/clew.svg">
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
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
|
+
</head>
|
|
13
|
+
<body>
|
|
14
|
+
<header class="header"></header>
|
|
15
|
+
<div id="sidebarOverlay" class="sidebar-overlay"></div>
|
|
16
|
+
<aside id="sidebar" class="sidebar"></aside>
|
|
17
|
+
|
|
18
|
+
<div class="content-wrap">
|
|
19
|
+
<div class="content">
|
|
20
|
+
|
|
21
|
+
<div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span class="current">Security</span></div>
|
|
22
|
+
|
|
23
|
+
<h1>Security</h1>
|
|
24
|
+
|
|
25
|
+
<h2 id="overview">License Notice</h2>
|
|
26
|
+
<p>Clew Code is an unofficial, reverse-engineered rebuild of Anthropic's Claude Code CLI, renamed and extended for research, local development, and self-hosted use. This repository is not an official Anthropic product. Anthropic has not authorized, endorsed, or sponsored this project.</p>
|
|
27
|
+
<p>The upstream Claude Code product is proprietary software owned by Anthropic PBC.</p>
|
|
28
|
+
|
|
29
|
+
<h2 id="api-keys">API Key Safety</h2>
|
|
30
|
+
<p>Clew Code reads API keys from environment variables or <code>.env</code> files. Keys are never committed or shared:</p>
|
|
31
|
+
<ul>
|
|
32
|
+
<li>Keep API keys in environment variables or <code>.env</code> (already in <code>.gitignore</code>)</li>
|
|
33
|
+
<li>Never include keys in prompts or tool calls</li>
|
|
34
|
+
<li>Use <code>/doctor</code> to verify provider connectivity without exposing secrets</li>
|
|
35
|
+
</ul>
|
|
36
|
+
|
|
37
|
+
<h2 id="permissions">Permission Security</h2>
|
|
38
|
+
<p>Clew Code's 7-tier permission model prevents unauthorized operations:</p>
|
|
39
|
+
<ul>
|
|
40
|
+
<li><strong>default/ask</strong> — user must approve every action</li>
|
|
41
|
+
<li><strong>auto</strong> — safe operations auto-approved, destructive ones still ask</li>
|
|
42
|
+
<li><strong>dontAsk</strong> — full trust. Use only in sandboxed environments</li>
|
|
43
|
+
</ul>
|
|
44
|
+
<p>See <a href="permission-model.html">Permission Model</a> for details.</p>
|
|
45
|
+
|
|
46
|
+
<h2 id="safety">Safety Gates</h2>
|
|
47
|
+
<p>The built-in safety gate system validates:</p>
|
|
48
|
+
<ul>
|
|
49
|
+
<li>Command paths — blocks dangerous shell commands</li>
|
|
50
|
+
<li>File paths — prevents writes outside project boundaries</li>
|
|
51
|
+
<li>Output limits — 100 MB bash output cap</li>
|
|
52
|
+
<li>Malformed tool call guard — prevents injection attacks</li>
|
|
53
|
+
<li>PowerShell rule enforcement on Windows</li>
|
|
54
|
+
</ul>
|
|
55
|
+
|
|
56
|
+
<h2 id="responsible-disclosure">Responsible Disclosure</h2>
|
|
57
|
+
<p>If you discover a security vulnerability, please open an issue on <a href="https://github.com/ClewCode/ClewCode/issues">GitHub</a> rather than posting publicly. Do not submit vulnerabilities as regular issues — use the security issue template.</p>
|
|
58
|
+
|
|
59
|
+
<h2 id="reporting">Reporting a Vulnerability</h2>
|
|
60
|
+
<p>To report a security issue, please:</p>
|
|
61
|
+
<ol>
|
|
62
|
+
<li>Go to <a href="https://github.com/ClewCode/ClewCode/security">github.com/ClewCode/ClewCode/security</a></li>
|
|
63
|
+
<li>Click "Report a vulnerability"</li>
|
|
64
|
+
<li>Include as much context as possible (OS, version, steps to reproduce)</li>
|
|
65
|
+
</ol>
|
|
66
|
+
</div>
|
|
67
|
+
</div>
|
|
68
|
+
|
|
69
|
+
<script src="js/main.js"></script>
|
|
70
|
+
</body>
|
|
71
|
+
</html>
|
package/docs/skills.html
CHANGED
|
@@ -1,117 +1,67 @@
|
|
|
1
|
-
<!DOCTYPE html>
|
|
2
|
-
<html lang="en">
|
|
3
|
-
<head>
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
<
|
|
15
|
-
<
|
|
16
|
-
<
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
<tr><
|
|
33
|
-
</
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
---</code></pre>
|
|
69
|
-
<p>Key frontmatter fields:</p>
|
|
70
|
-
<ul>
|
|
71
|
-
<li><code>allowed-tools</code> — Restrict which tools the model can use while this skill is active</li>
|
|
72
|
-
<li><code>disallowed-tools</code> — Explicitly block tools (e.g., <code>Bash</code>, <code>Edit</code>) for read-only skills</li>
|
|
73
|
-
<li><code>hooks</code> — Register PreToolUse, PostToolUse, or MessageDisplay hooks for the skill</li>
|
|
74
|
-
<li><code>model</code> — Override the model used when this skill runs</li>
|
|
75
|
-
<li><code>effort</code> — Set effort level (low, medium, high, xhigh, max)</li>
|
|
76
|
-
<li><code>context</code> — <code>inline</code> (default) expands into current conversation; <code>fork</code> runs as sub-agent</li>
|
|
77
|
-
</ul>
|
|
78
|
-
|
|
79
|
-
<h2>Creating a Skill</h2>
|
|
80
|
-
<pre><code>mkdir -p ~/.clew/skills/my-skill
|
|
81
|
-
touch ~/.clew/skills/my-skill/SKILL.md
|
|
82
|
-
# Edit SKILL.md with frontmatter and instructions</code></pre>
|
|
83
|
-
<p>Or use the <code>skillify</code> plugin to create a skill from an existing workflow.</p>
|
|
84
|
-
|
|
85
|
-
<h2>Project-Level Skills</h2>
|
|
86
|
-
<p>Place skills in <code>.clew/skills/</code> inside your repository to share with your team:</p>
|
|
87
|
-
<pre><code>.clew/
|
|
88
|
-
skills/
|
|
89
|
-
code-review/
|
|
90
|
-
SKILL.md
|
|
91
|
-
migration-workflow/
|
|
92
|
-
SKILL.md</code></pre>
|
|
93
|
-
<p>Project skills are automatically available to everyone working in the repository.</p>
|
|
94
|
-
|
|
95
|
-
<h2>Dynamic Skills</h2>
|
|
96
|
-
<p>Skills can be discovered dynamically during file operations. When a skill file is created or modified, it's automatically added to the available command list without restarting. Use <code>clearCommandMemoizationCaches()</code> to refresh the skill index.</p>
|
|
97
|
-
|
|
98
|
-
<div class="callout callout-info">
|
|
99
|
-
<strong>Skills vs. Plugins</strong>
|
|
100
|
-
Skills are instruction-only (markdown), no code required. Plugins provide executable JavaScript — commands, hooks, agents, MCP servers. Use skills to standardize AI behavior; use plugins for custom tooling.
|
|
101
|
-
</div>
|
|
102
|
-
|
|
103
|
-
<footer class="footer">
|
|
104
|
-
<span>Clew Code 0.2.14 — Open Source</span>
|
|
105
|
-
<div class="footer-links">
|
|
106
|
-
<a href="https://github.com/ClewCode/ClewCode">GitHub</a>
|
|
107
|
-
<a href="https://github.com/ClewCode/ClewCode/issues">Issues</a>
|
|
108
|
-
</div>
|
|
109
|
-
</footer>
|
|
110
|
-
</main>
|
|
111
|
-
<nav class="toc-sidebar"></nav>
|
|
112
|
-
</div>
|
|
113
|
-
</div>
|
|
114
|
-
<script src="js/main.js"></script>
|
|
115
|
-
</body>
|
|
116
|
-
</html>
|
|
117
|
-
|
|
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>Skills — Clew Code</title>
|
|
7
|
+
<meta name="description" href="The skills system in Clew Code — Claude Code compatible.">
|
|
8
|
+
<link rel="icon" type="image/svg+xml" href="assets/clew.svg">
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
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
|
+
</head>
|
|
13
|
+
<body>
|
|
14
|
+
<header class="header"></header>
|
|
15
|
+
<div id="sidebarOverlay" class="sidebar-overlay"></div>
|
|
16
|
+
<aside id="sidebar" class="sidebar"></aside>
|
|
17
|
+
|
|
18
|
+
<div class="content-wrap">
|
|
19
|
+
<div class="content">
|
|
20
|
+
|
|
21
|
+
<div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span class="current">Skills</span></div>
|
|
22
|
+
|
|
23
|
+
<h1>Skills</h1>
|
|
24
|
+
<p class="sub">Skills are reusable, invocable capabilities that extend Clew Code with domain-specific expertise. The skills system is Claude Code compatible.</p>
|
|
25
|
+
|
|
26
|
+
<h2 id="overview">Overview</h2>
|
|
27
|
+
<p>Skills are defined in <code>SKILL.md</code> files and matched by name or description. When a user or agent invokes a skill, its prompt is loaded into the conversation, providing specialized instructions and context.</p>
|
|
28
|
+
|
|
29
|
+
<h2 id="builtin">Built-in Skills</h2>
|
|
30
|
+
<table>
|
|
31
|
+
<thead>
|
|
32
|
+
<tr><th>Skill</th><th>Description</th></tr>
|
|
33
|
+
</thead>
|
|
34
|
+
<tbody>
|
|
35
|
+
<tr><td><code>/verify</code></td><td>Run full verification — typecheck, lint, and tests</td></tr>
|
|
36
|
+
<tr><td><code>/precommit</code></td><td>Pre-commit review with verification and git diff summary</td></tr>
|
|
37
|
+
<tr><td><code>/commit</code></td><td>Stage, commit, and push git changes with conventional commits</td></tr>
|
|
38
|
+
<tr><td><code>/code-review</code></td><td>Review code for correctness bugs at configurable effort</td></tr>
|
|
39
|
+
<tr><td><code>/loop</code></td><td>Run a prompt or command on a recurring interval</td></tr>
|
|
40
|
+
<tr><td><code>/update-config</code></td><td>Configure Clew Code via settings.json</td></tr>
|
|
41
|
+
<tr><td><code>/scrapling</code></td><td>Web scraping using Scrapling framework</td></tr>
|
|
42
|
+
</tbody>
|
|
43
|
+
</table>
|
|
44
|
+
|
|
45
|
+
<h2 id="creating">Creating a Skill</h2>
|
|
46
|
+
<p>Create a <code>SKILL.md</code> file in your project:</p>
|
|
47
|
+
<pre><code class="language-markdown"># my-skill
|
|
48
|
+
|
|
49
|
+
Invoke with `/my-skill [args]`.
|
|
50
|
+
|
|
51
|
+
## Instructions
|
|
52
|
+
|
|
53
|
+
Provide detailed instructions for what this skill should do.
|
|
54
|
+
Include context, constraints, and examples.
|
|
55
|
+
</code></pre>
|
|
56
|
+
<p>Skills are automatically discovered from the project root.</p>
|
|
57
|
+
|
|
58
|
+
<h2 id="skill-commands">Skill Commands</h2>
|
|
59
|
+
<pre><code class="language-bash">❯ /skills # list all available skills
|
|
60
|
+
❯ /my-skill args # invoke a specific skill with arguments
|
|
61
|
+
</code></pre>
|
|
62
|
+
</div>
|
|
63
|
+
</div>
|
|
64
|
+
|
|
65
|
+
<script src="js/main.js"></script>
|
|
66
|
+
</body>
|
|
67
|
+
</html>
|
package/docs/swarm.html
CHANGED
|
@@ -1,236 +1,78 @@
|
|
|
1
|
-
<!DOCTYPE html>
|
|
2
|
-
<html lang="en">
|
|
3
|
-
<head>
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
<
|
|
15
|
-
<
|
|
16
|
-
<
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
│ POST /peer-exec ──► run shell command + return stdout/stderr
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
═══ CLIENT (Machine B) SWARM TOOLS ═══
|
|
83
|
-
|
|
84
|
-
/swarm discover ──► scan files + UDP query (3s timeout)
|
|
85
|
-
│
|
|
86
|
-
▼
|
|
87
|
-
[peer list]
|
|
88
|
-
│
|
|
89
|
-
┌───────────────────┼───────────────────┐
|
|
90
|
-
▼ ▼ ▼
|
|
91
|
-
/swarm join /swarm send_task /swarm run
|
|
92
|
-
(POST /peer-info) (POST /peer-todo) (POST /peer-exec)
|
|
93
|
-
|
|
94
|
-
│
|
|
95
|
-
▼
|
|
96
|
-
/swarm send_message ──► POST /peer-msg ──► destination inbox
|
|
97
|
-
/swarm broadcast ──► POST /peer-msg ──► all connected swarm nodes
|
|
98
|
-
/swarm 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>/swarm 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>~/.clew/peers/{pid}.json</code> with hostname, IP, port, shell, cwd. Other instances scan this directory to discover local swarm nodes.</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>/swarm</code></td><td>Open interactive peer menu (share, join, discover, inbox)</td></tr>
|
|
168
|
-
<tr><td><code>/swarm share</code></td><td>Start advertising this instance as a worker on the LAN</td></tr>
|
|
169
|
-
<tr><td><code>/swarm stop</code></td><td>Stop advertising and shut down the swarm server</td></tr>
|
|
170
|
-
<tr><td><code>/swarm discover</code></td><td>Scan for available swarm nodes (file + UDP, 3s timeout)</td></tr>
|
|
171
|
-
<tr><td><code>/swarm join <host> <port></code></td><td>Connect to a remote swarm node by host and port</td></tr>
|
|
172
|
-
<tr><td><code>/swarm name <name></code></td><td>Set a custom display name for yourself</td></tr>
|
|
173
|
-
<tr><td><code>/swarm role <role></code></td><td>Set a role label (builder, tester, deployer, etc.)</td></tr>
|
|
174
|
-
<tr><td><code>/swarm inbox</code></td><td>View pending messages and todos from peers</td></tr>
|
|
175
|
-
<tr><td><code>/swarm disconnect <peer></code></td><td>Disconnect from a specific swarm node</td></tr>
|
|
176
|
-
<tr><td><code>/swarm todos</code></td><td>List all received tasks</td></tr>
|
|
177
|
-
<tr><td><code>/swarm todo done <id></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 swarm 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 swarm node 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 swarm nodes 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 swarm nodes 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 swarm nodes:</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>/swarm 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 swarm 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/swarm/</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 swarm 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 0.2.14 — 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
|
-
|
|
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>Swarm System — Clew Code</title>
|
|
7
|
+
<meta name="description" content="Multi-agent swarm coordination in Clew Code.">
|
|
8
|
+
<link rel="icon" type="image/svg+xml" href="assets/clew.svg">
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
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
|
+
</head>
|
|
13
|
+
<body>
|
|
14
|
+
<header class="header"></header>
|
|
15
|
+
<div id="sidebarOverlay" class="sidebar-overlay"></div>
|
|
16
|
+
<aside id="sidebar" class="sidebar"></aside>
|
|
17
|
+
|
|
18
|
+
<div class="content-wrap">
|
|
19
|
+
<div class="content">
|
|
20
|
+
|
|
21
|
+
<div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span class="current">Swarm System</span></div>
|
|
22
|
+
|
|
23
|
+
<h1>Swarm System</h1>
|
|
24
|
+
<p class="sub">Coordinate multiple AI agents working together on complex tasks.</p>
|
|
25
|
+
|
|
26
|
+
<h2 id="overview">Overview</h2>
|
|
27
|
+
<p>The swarm system enables multiple agent instances to work together as a team. Each agent has an identity, mailbox, task queue, and can communicate with other agents in the swarm.</p>
|
|
28
|
+
|
|
29
|
+
<h2 id="architecture">Architecture</h2>
|
|
30
|
+
<pre><code>Agent A (Coordinator)
|
|
31
|
+
├── Agent B (Researcher)
|
|
32
|
+
│ └── Agent D (Data Collector)
|
|
33
|
+
├── Agent C (Implementer)
|
|
34
|
+
└── Agent E (Reviewer)
|
|
35
|
+
</code></pre>
|
|
36
|
+
|
|
37
|
+
<p>Agents communicate via a message bus. Each agent has its own:</p>
|
|
38
|
+
<ul>
|
|
39
|
+
<li><strong>Identity</strong> — name, role, capabilities</li>
|
|
40
|
+
<li><strong>Mailbox</strong> — receives messages from other agents</li>
|
|
41
|
+
<li><strong>Task queue</strong> — pending and completed tasks</li>
|
|
42
|
+
<li><strong>Result channel</strong> — output is collected by the coordinator</li>
|
|
43
|
+
</ul>
|
|
44
|
+
|
|
45
|
+
<h2 id="execution">Execution Modes</h2>
|
|
46
|
+
<table>
|
|
47
|
+
<thead>
|
|
48
|
+
<tr><th>Mode</th><th>Description</th></tr>
|
|
49
|
+
</thead>
|
|
50
|
+
<tbody>
|
|
51
|
+
<tr><td>Pane/tmux</td><td>Each agent runs in its own terminal pane</td></tr>
|
|
52
|
+
<tr><td>In-process</td><td>Agents run as lightweight coroutines within the same process</td></tr>
|
|
53
|
+
</tbody>
|
|
54
|
+
</table>
|
|
55
|
+
|
|
56
|
+
<h2 id="vs-subagent">Swarm vs. Subagent</h2>
|
|
57
|
+
<table>
|
|
58
|
+
<thead>
|
|
59
|
+
<tr><th>Subagent</th><th>Swarm/Teammate</th></tr>
|
|
60
|
+
</thead>
|
|
61
|
+
<tbody>
|
|
62
|
+
<tr><td>One-shot, isolated</td><td>Persistent, collaborative</td></tr>
|
|
63
|
+
<tr><td>No inter-agent communication</td><td>Full mailbox system</td></tr>
|
|
64
|
+
<tr><td>Results returned once</td><td>Continuous coordination</td></tr>
|
|
65
|
+
<tr><td>Best for exploration</td><td>Best for long-running complex tasks</td></tr>
|
|
66
|
+
</tbody>
|
|
67
|
+
</table>
|
|
68
|
+
|
|
69
|
+
<h2 id="commands">Swarm Commands</h2>
|
|
70
|
+
<pre><code class="language-bash">❯ /agents # open agent dashboard
|
|
71
|
+
❯ /agent dispatch ... # dispatch a subagent
|
|
72
|
+
</code></pre>
|
|
73
|
+
</div>
|
|
74
|
+
</div>
|
|
75
|
+
|
|
76
|
+
<script src="js/main.js"></script>
|
|
77
|
+
</body>
|
|
78
|
+
</html>
|