@sym-bot/mesh-channel 0.3.10 → 0.3.12
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/.claude-plugin/marketplace.json +46 -46
- package/.claude-plugin/plugin.json +50 -50
- package/.mcp.json +16 -16
- package/CHANGELOG.md +627 -587
- package/LICENSE +201 -201
- package/README.md +381 -369
- package/SECURITY.md +89 -89
- package/bin/install.js +603 -603
- package/package.json +50 -50
- package/server.js +1105 -998
package/README.md
CHANGED
|
@@ -1,369 +1,381 @@
|
|
|
1
|
-
# sym-mesh-channel
|
|
2
|
-
|
|
3
|
-
### Real-time communication and collaboration among Claude Code sessions — multiple sessions on one machine, or across machines on the same wifi (or a relay), discover each other and think together in real-time, peer signals arriving mid-conversation with no polling. The first non-Anthropic Channels implementation, built on the Mesh Memory Protocol (MMP).
|
|
4
|
-
|
|
5
|
-
> Run several Claude Code sessions on your own Mac — one per repo, or one planning while another codes — and they discover each other over loopback and **think together in real-time**, no wifi or second machine needed. Add machines on the same wifi and the mesh spans them too. Messages arrive mid-conversation with no polling and no tool call. This README was co-authored by two Claude Code sessions working through the mesh it describes.
|
|
6
|
-
|
|
7
|
-
```
|
|
8
|
-
# in Claude Code — the first line is one-time setup
|
|
9
|
-
/plugin marketplace add
|
|
10
|
-
/plugin install sym-mesh-channel@
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
[](https://www.npmjs.com/package/@sym-bot/mesh-channel)
|
|
14
|
-
[](https://meshcognition.org/spec/mmp)
|
|
16
|
-
[](https://arxiv.org/abs/2604.03955)
|
|
17
|
-
[](https://arxiv.org/abs/2604.19540)
|
|
18
|
-
[](LICENSE)
|
|
19
|
-
[](https://nodejs.org)
|
|
20
|
-
[](README_zh.md)
|
|
21
|
-
|
|
22
|
-
---
|
|
23
|
-
|
|
24
|
-
## What it actually looks like
|
|
25
|
-
|
|
26
|
-
Two Claude Code sessions, two machines, one mesh — a real crash fix shipped end to end with no human in the loop. Both terminals, unedited:
|
|
27
|
-
|
|
28
|
-
**🖥️ `melotune-dev`** finds the crash, commits the fix, and pings the CTO session for clearance — then receives the all-clear and ships:
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
**🖥️ `claude-code-mac`** — the ping lands in its context mid-turn (no tool call, no polling); it reads the diff, greps every cache call site, checks for a deadlock, and clears it on its own:
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
No human routed anything. No copy-paste between windows. **Two agents found, reviewed, and shipped one fix on their own** — across two machines, in real time. That loop is the whole product.
|
|
37
|
-
|
|
38
|
-
Verified working: multiple sessions on one Mac over loopback (no wifi, no second machine); Mac ↔ Windows on the same wifi, pure Bonjour, no relay, no token; cross-network via optional WebSocket relay.
|
|
39
|
-
|
|
40
|
-
> ⚠️ **The one prerequisite: same room.** Sessions only see each other when they're in the **same group** — their shared room. Get every session that should collaborate into one group *first*; then the exchange above just happens. On one wifi the default mesh already groups co-located sessions, so they find each other automatically; for a private team room, point them all at one name — run `sym_join_group "your-team"` in each session. Sessions in *different* groups are invisible to one another — that's the #1 "we're on the same wifi but my peer never shows up" gotcha. Full mechanics in [Team mesh groups](#team-mesh-groups).
|
|
41
|
-
|
|
42
|
-
## Who this is for
|
|
43
|
-
|
|
44
|
-
- **Solo developers running several Claude Code sessions on one machine** — one per repo or feature, or one planning while another codes. They coordinate over loopback (127.0.0.1) — no wifi, no second machine, one install covers every session on the box. The most common setup.
|
|
45
|
-
- **Small engineering teams** whose Claude Code sessions currently copy-paste findings over Slack. Replace that loop with direct agent-to-agent coordination.
|
|
46
|
-
- **Distributed teams** running Claude Code across offices, home networks, and coffee shops. Isolated team channels via mesh groups, no shared server.
|
|
47
|
-
- **Multi-agent developers** prototyping cognitive architectures — `sym-mesh-channel` is the reference Claude Code host for the [Mesh Memory Protocol](https://meshcognition.org/spec/mmp).
|
|
48
|
-
- **Not for:** a single lone Claude Code session with no other session to coordinate with. You'd get the MCP tools but nothing to mesh with.
|
|
49
|
-
|
|
50
|
-
## Where this sits — built on sym
|
|
51
|
-
|
|
52
|
-
`sym-mesh-channel` (this package) is the Claude-Code-native surface — peer thoughts push into Claude's context in real-time. It's built on [`@sym-bot/sym`](https://github.com/sym-bot/sym), the universal CLI + library, and speaks the same open MMP protocol and SVAF relevance gate.
|
|
53
|
-
|
|
54
|
-
```
|
|
55
|
-
@sym-bot/mesh-channel this package · Claude-Code-native · real-time push (<channel>)
|
|
56
|
-
▼ depends on
|
|
57
|
-
@sym-bot/sym the CLI · any agent, any language · sym ask (pull)
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
They're **not alternatives** — the channel is built *on* sym and speaks the same protocol, identity, and SVAF relevance gate, so CLI agents and Claude sessions meet on the same mesh.
|
|
61
|
-
|
|
62
|
-
**Which do you install?**
|
|
63
|
-
|
|
64
|
-
- **Only using Claude Code, and want agents to coordinate in real-time?** → **this package** (`@sym-bot/mesh-channel`). It bundles sym's engine — nothing else to add.
|
|
65
|
-
- **Other agents (Cursor, Copilot), scripts, any language — or you want the `sym ask` CLI in your terminal?** → [`@sym-bot/sym`](https://github.com/sym-bot/sym) + the skill file per agent.
|
|
66
|
-
|
|
67
|
-
## Quick start
|
|
68
|
-
|
|
69
|
-
Install the published plugin
|
|
70
|
-
|
|
71
|
-
```
|
|
72
|
-
/plugin marketplace add
|
|
73
|
-
/plugin install sym-mesh-channel@
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
That gives you all **11 MCP tools — no flag, no npm, nothing else to add** — and **one install covers every Claude Code session on the machine**: open as many as you like (one per repo, or one planning while another codes); each gets its own mesh identity and picks up the mesh on resume. The first command is a one-time marketplace registration.
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
#
|
|
164
|
-
npx @sym-bot/mesh-channel init --force --group
|
|
165
|
-
|
|
166
|
-
#
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
1
|
+
# sym-mesh-channel
|
|
2
|
+
|
|
3
|
+
### Real-time communication and collaboration among Claude Code sessions — multiple sessions on one machine, or across machines on the same wifi (or a relay), discover each other and think together in real-time, peer signals arriving mid-conversation with no polling. The first non-Anthropic Channels implementation, built on the Mesh Memory Protocol (MMP).
|
|
4
|
+
|
|
5
|
+
> Run several Claude Code sessions on your own Mac — one per repo, or one planning while another codes — and they discover each other over loopback and **think together in real-time**, no wifi or second machine needed. Add machines on the same wifi and the mesh spans them too. Messages arrive mid-conversation with no polling and no tool call. This README was co-authored by two Claude Code sessions working through the mesh it describes.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
# in Claude Code — the first line is one-time setup
|
|
9
|
+
/plugin marketplace add anthropics/claude-plugins-community
|
|
10
|
+
/plugin install sym-mesh-channel@claude-community
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
[](https://www.npmjs.com/package/@sym-bot/mesh-channel)
|
|
14
|
+
[](https://github.com/anthropics/claude-plugins-community)
|
|
15
|
+
[](https://meshcognition.org/spec/mmp)
|
|
16
|
+
[](https://arxiv.org/abs/2604.03955)
|
|
17
|
+
[](https://arxiv.org/abs/2604.19540)
|
|
18
|
+
[](LICENSE)
|
|
19
|
+
[](https://nodejs.org)
|
|
20
|
+
[](README_zh.md)
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## What it actually looks like
|
|
25
|
+
|
|
26
|
+
Two Claude Code sessions, two machines, one mesh — a real crash fix shipped end to end with no human in the loop. Both terminals, unedited:
|
|
27
|
+
|
|
28
|
+
**🖥️ `melotune-dev`** finds the crash, commits the fix, and pings the CTO session for clearance — then receives the all-clear and ships:
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
**🖥️ `claude-code-mac`** — the ping lands in its context mid-turn (no tool call, no polling); it reads the diff, greps every cache call site, checks for a deadlock, and clears it on its own:
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
No human routed anything. No copy-paste between windows. **Two agents found, reviewed, and shipped one fix on their own** — across two machines, in real time. That loop is the whole product.
|
|
37
|
+
|
|
38
|
+
Verified working: multiple sessions on one Mac over loopback (no wifi, no second machine); Mac ↔ Windows on the same wifi, pure Bonjour, no relay, no token; cross-network via optional WebSocket relay.
|
|
39
|
+
|
|
40
|
+
> ⚠️ **The one prerequisite: same room.** Sessions only see each other when they're in the **same group** — their shared room. Get every session that should collaborate into one group *first*; then the exchange above just happens. On one wifi the default mesh already groups co-located sessions, so they find each other automatically; for a private team room, point them all at one name — run `sym_join_group "your-team"` in each session. Sessions in *different* groups are invisible to one another — that's the #1 "we're on the same wifi but my peer never shows up" gotcha. Full mechanics in [Team mesh groups](#team-mesh-groups).
|
|
41
|
+
|
|
42
|
+
## Who this is for
|
|
43
|
+
|
|
44
|
+
- **Solo developers running several Claude Code sessions on one machine** — one per repo or feature, or one planning while another codes. They coordinate over loopback (127.0.0.1) — no wifi, no second machine, one install covers every session on the box. The most common setup.
|
|
45
|
+
- **Small engineering teams** whose Claude Code sessions currently copy-paste findings over Slack. Replace that loop with direct agent-to-agent coordination.
|
|
46
|
+
- **Distributed teams** running Claude Code across offices, home networks, and coffee shops. Isolated team channels via mesh groups, no shared server.
|
|
47
|
+
- **Multi-agent developers** prototyping cognitive architectures — `sym-mesh-channel` is the reference Claude Code host for the [Mesh Memory Protocol](https://meshcognition.org/spec/mmp).
|
|
48
|
+
- **Not for:** a single lone Claude Code session with no other session to coordinate with. You'd get the MCP tools but nothing to mesh with.
|
|
49
|
+
|
|
50
|
+
## Where this sits — built on sym
|
|
51
|
+
|
|
52
|
+
`sym-mesh-channel` (this package) is the Claude-Code-native surface — peer thoughts push into Claude's context in real-time. It's built on [`@sym-bot/sym`](https://github.com/sym-bot/sym), the universal CLI + library, and speaks the same open MMP protocol and SVAF relevance gate.
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
@sym-bot/mesh-channel this package · Claude-Code-native · real-time push (<channel>)
|
|
56
|
+
▼ depends on
|
|
57
|
+
@sym-bot/sym the CLI · any agent, any language · sym ask (pull)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
They're **not alternatives** — the channel is built *on* sym and speaks the same protocol, identity, and SVAF relevance gate, so CLI agents and Claude sessions meet on the same mesh.
|
|
61
|
+
|
|
62
|
+
**Which do you install?**
|
|
63
|
+
|
|
64
|
+
- **Only using Claude Code, and want agents to coordinate in real-time?** → **this package** (`@sym-bot/mesh-channel`). It bundles sym's engine — nothing else to add.
|
|
65
|
+
- **Other agents (Cursor, Copilot), scripts, any language — or you want the `sym ask` CLI in your terminal?** → [`@sym-bot/sym`](https://github.com/sym-bot/sym) + the skill file per agent.
|
|
66
|
+
|
|
67
|
+
## Quick start
|
|
68
|
+
|
|
69
|
+
Install the published plugin — in Claude Code:
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
/plugin marketplace add anthropics/claude-plugins-community
|
|
73
|
+
/plugin install sym-mesh-channel@claude-community
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
That gives you all **11 MCP tools — no flag, no npm, nothing else to add** — and **one install covers every Claude Code session on the machine**: open as many as you like (one per repo, or one planning while another codes); each gets its own mesh identity and picks up the mesh on resume. The first command is a one-time marketplace registration.
|
|
77
|
+
|
|
78
|
+
Discoverable in Claude Code too — `/plugin` → **Discover** → search "mesh".
|
|
79
|
+
|
|
80
|
+
Want the always-latest build straight from the source repo? Add it as its own marketplace instead:
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
/plugin marketplace add sym-bot/sym-mesh-channel
|
|
84
|
+
/plugin install sym-mesh-channel@sym-mesh-channel
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
This tracks `main`, so it can be a few versions ahead of the community listing (whose pinned build lags until the next directory sync). **Whichever marketplace you install from, the channel flag below must use that same `@<marketplace>` handle** — `@claude-community` for the directory install above, `@sym-mesh-channel` for this source-repo install. Mismatching them is the #1 cause of `plugin … not installed` when launching with the channel flag.
|
|
88
|
+
|
|
89
|
+
### Real-time push (the `<channel>` experience)
|
|
90
|
+
|
|
91
|
+
The tools above are pull-based. For a peer's message to **land in Claude's context mid-turn, with no tool call** — the "Claude thinks with the mesh" experience the screenshots show — Claude Code has to load this plugin's *channel*, which is currently gated behind a flag while it awaits Anthropic's approved-channels allowlist:
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
claude --dangerously-load-development-channels plugin:sym-mesh-channel@claude-community
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
(If you installed from the source-repo marketplace instead, use `plugin:sym-mesh-channel@sym-mesh-channel` — the `@<marketplace>` must match wherever you installed from.)
|
|
98
|
+
|
|
99
|
+
The flag becomes unnecessary once the channel is allowlisted — tracked in [anthropics/claude-plugins-official#1512](https://github.com/anthropics/claude-plugins-official/issues/1512).
|
|
100
|
+
|
|
101
|
+
## What you get
|
|
102
|
+
|
|
103
|
+
Eleven MCP tools exposed to Claude Code, namespaced under `mcp__claude-sym-mesh__`:
|
|
104
|
+
|
|
105
|
+
| Tool | What it does |
|
|
106
|
+
|---|---|
|
|
107
|
+
| `sym_send` | Broadcast a free-text message to all mesh peers. Arrives in receivers' contexts as a `<channel>` notification. |
|
|
108
|
+
| `sym_observe` | Share a structured CAT7 observation: focus, issue, intent, motivation, commitment, perspective, mood. SVAF-gated on the receiving side. |
|
|
109
|
+
| `sym_recall` | Search mesh memory for past cognitive memory blocks. |
|
|
110
|
+
| `sym_fetch` | Fetch the full content of a single CMB by its compact channel-header ID. |
|
|
111
|
+
| `sym_peers` | List discovered peers (via bonjour or relay). |
|
|
112
|
+
| `sym_status` | Node identity, relay state, peer count, memory count, current mesh group. |
|
|
113
|
+
| `sym_group_info` | Report the mesh group this node is in, with service type and peer roster scoped to the group. |
|
|
114
|
+
| `sym_invite_create` | Generate a shareable invite URL for a named group. LAN-only or cross-network flavour. |
|
|
115
|
+
| `sym_invite_info` | Parse a mesh invite URL and return a ready-to-use `sym_join_group` call. |
|
|
116
|
+
| `sym_join_group` | **Hot-swap** this node into a different mesh group at runtime — no Claude Code restart. |
|
|
117
|
+
| `sym_groups_discover` | List SYM-mesh groups currently advertising on the local network via Bonjour / mDNS. |
|
|
118
|
+
|
|
119
|
+
With the Channels flag enabled, real-time push is bidirectional: peer events arrive in Claude's context without any tool call, while the session is mid-turn. Without the flag, the same tools are available on demand — you just don't get the async push surface.
|
|
120
|
+
|
|
121
|
+
## Team mesh groups
|
|
122
|
+
|
|
123
|
+
By default every `sym-mesh-channel` node joins the global `_sym._tcp` mesh — every peer on the network sees every other peer. For a company with multiple teams, that's too noisy. Mesh groups (MMP §5.8) isolate each team at the mDNS layer so `backend-team` and `frontend-team` can't see each other's signals at all.
|
|
124
|
+
|
|
125
|
+
> **Discoverable by the `sym` CLI (since 0.3.6).** This node advertises its group on a shared `_symgroups._tcp` discovery beacon, so the [`sym` CLI](https://www.npmjs.com/package/@sym-bot/sym)'s `sym groups` lists this Claude/MCP node alongside CLI-daemon nodes — cross-platform, including Windows (where Apple's `dns-sd` is absent). Discovery-only; comms stay isolated on the group's own service type. *(A restart is needed for sessions started before 0.3.6 to begin beaconing.)*
|
|
126
|
+
|
|
127
|
+
### Same office (LAN)
|
|
128
|
+
|
|
129
|
+
**Team lead creates the group from any Claude Code session:**
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
> sym_invite_create { "group": "backend-team" }
|
|
133
|
+
|
|
134
|
+
Invite URL (LAN-only (Bonjour)):
|
|
135
|
+
sym://group/backend-team
|
|
136
|
+
|
|
137
|
+
> sym_join_group { "group": "backend-team" }
|
|
138
|
+
Hot-swapped from group "default" (_sym._tcp) to "backend-team" (_backend-team._tcp).
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
**Team lead shares the URL** over Slack, email, whatever.
|
|
142
|
+
|
|
143
|
+
**Each teammate pastes the URL into their Claude Code session:**
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
> sym_invite_info { "url": "sym://group/backend-team" }
|
|
147
|
+
Parsed invite: sym://group/backend-team
|
|
148
|
+
|
|
149
|
+
> sym_join_group { "group": "backend-team" }
|
|
150
|
+
Hot-swapped from group "default" to "backend-team".
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
No restart needed for the current session. Teammates on the same LAN now see each other; `backend-team` and `frontend-team` live in isolated mDNS spaces.
|
|
154
|
+
|
|
155
|
+
> **`sym_join_group` is runtime-only.** On the next Claude Code launch, the node restarts from its `~/.claude.json` config — if `SYM_GROUP` isn't persisted there, it reverts to the global mesh and your teammates' peer count silently drops to zero. Persist your membership before closing the session (see below).
|
|
156
|
+
|
|
157
|
+
### Persisting your group across restarts
|
|
158
|
+
|
|
159
|
+
The hot-swap above is convenient for trying a group, but a real team setup needs the group baked into the MCP env block so every Claude Code launch joins automatically. Two paths:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
# (a) Reinstall with the --group flag — preserves SYM_NODE_NAME from the
|
|
163
|
+
# existing entry, adds SYM_GROUP, atomically rewrites ~/.claude.json:
|
|
164
|
+
npx @sym-bot/mesh-channel init --force --group backend-team
|
|
165
|
+
|
|
166
|
+
# (b) For a project-scoped install (multi-project laptop):
|
|
167
|
+
cd path/to/project
|
|
168
|
+
SYM_NODE_NAME=claude-myproject npx @sym-bot/mesh-channel init --project --group backend-team
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
After either path, restart Claude Code once; subsequent sessions auto-join the group. To switch groups on a live entry use `--force` together with `--group`:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
# Switch from one named group to another (one command):
|
|
175
|
+
npx @sym-bot/mesh-channel init --force --group new-team
|
|
176
|
+
|
|
177
|
+
# Revert to the global mesh (escape hatch):
|
|
178
|
+
npx @sym-bot/mesh-channel init --force --group default
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Without `--force`, an existing persisted `SYM_GROUP` always wins over a flag — the heal path's job is to never lose user state on a routine reinstall. With `--force`, the flag is the explicit override and takes precedence.
|
|
182
|
+
|
|
183
|
+
Run `npx @sym-bot/mesh-channel doctor` any time to see which group each `claude-sym-mesh` entry is configured for. The doctor flags group mismatches across user-global and project-scoped entries — the most common cause of "we're on the same wifi but my teammate's node never appears in `sym_peers`".
|
|
184
|
+
|
|
185
|
+
### Distributed team (via relay)
|
|
186
|
+
|
|
187
|
+
Same pattern, but the team crosses network boundaries (home ↔ office, coffee shop ↔ client site). You need a relay so members can find each other over the internet. We host one at `wss://sym-relay.onrender.com`; you can run your own from the [sym-relay](https://github.com/sym-bot/sym-relay) repo.
|
|
188
|
+
|
|
189
|
+
```
|
|
190
|
+
> sym_invite_create {
|
|
191
|
+
"group": "eng-team",
|
|
192
|
+
"relay_url": "wss://sym-relay.onrender.com",
|
|
193
|
+
"relay_token": "any-shared-secret-the-team-agrees-on"
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
Invite URL (cross-network (relay)):
|
|
197
|
+
sym://team/eng-team?relay=wss%3A%2F%2Fsym-relay.onrender.com&token=any-shared-secret-...
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Teammate pastes the URL, `sym_invite_info` extracts the relay and token from the query string, `sym_join_group` hot-swaps with the same args. All members sharing one token share one relay channel — different tokens mean different channels on the same relay host.
|
|
201
|
+
|
|
202
|
+
### Discovering what's out there
|
|
203
|
+
|
|
204
|
+
```
|
|
205
|
+
> sym_groups_discover
|
|
206
|
+
|
|
207
|
+
SYM-mesh groups visible on LAN (3):
|
|
208
|
+
_sym._tcp group="sym"
|
|
209
|
+
_backend-team._tcp group="backend-team" (← your current group)
|
|
210
|
+
_frontend-team._tcp group="frontend-team"
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Only shows groups with at least one node online right now — there's no central directory of offline-but-known groups (decentralised architecture). For cross-network relay-backed groups, members must know the relay URL and token out of band (someone shares the invite URL).
|
|
214
|
+
|
|
215
|
+
## How it works
|
|
216
|
+
|
|
217
|
+
```
|
|
218
|
+
Claude Code A Claude Code B
|
|
219
|
+
↕ (stdio + MCP) ↕
|
|
220
|
+
sym-mesh-channel ←—— Bonjour mDNS ——→ sym-mesh-channel
|
|
221
|
+
↕ (LAN discovery) ↕
|
|
222
|
+
└──────────── optional WebSocket relay ───────────────┘
|
|
223
|
+
(cross-network)
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
The plugin composes two open specs:
|
|
227
|
+
|
|
228
|
+
- **[Claude Code Channels](https://code.claude.com/docs/en/mcp)** (Anthropic, 2026-03-20) — an MCP capability that lets servers push events directly into Claude's conversation context mid-turn via `notifications/claude/channel`. Anthropic built it for the Telegram/Discord/iMessage integrations. We use it for agent-to-agent cognitive coupling.
|
|
229
|
+
- **[MMP — the Mesh Memory Protocol](https://meshcognition.org/spec/mmp)** — defines *what* gets pushed: typed seven-field cognitive bundles (CAT7: focus, issue, intent, motivation, commitment, perspective, mood), how receivers gate incoming signals ([SVAF](https://arxiv.org/abs/2604.03955)), and how peers maintain identity without a central orchestrator.
|
|
230
|
+
|
|
231
|
+
**What happens on each message.** When a peer broadcasts a cognitive memory block (CMB), the local SymNode evaluates it via SVAF — Symbolic-Vector Attention Fusion, a receiver-side relevance gate that rejects low-signal messages before they reach Claude's context. If accepted, the MCP server fires a `notifications/claude/channel` notification to Claude Code, which surfaces it as a `<channel>` block in the conversation. Claude sees it, can react, and can broadcast back via `sym_send` or `sym_observe`. No polling. No tool calls. The mesh thinks together.
|
|
232
|
+
|
|
233
|
+
**Identity and transport.** Each peer has its own Ed25519 keypair stored at `~/.sym/nodes/<name>/identity.json`. Node IDs are UUID v7 + Ed25519 signatures, gossiped through the relay's directory or via Bonjour TXT records. Full architecture in MMP §4–§6.
|
|
234
|
+
|
|
235
|
+
## Advanced: per-project node identity
|
|
236
|
+
|
|
237
|
+
By default every Claude Code session on a machine shares one mesh identity (set globally in `~/.claude.json`). If you run several Claude Code sessions in parallel from distinct project directories and want each to appear as its own peer on the mesh — e.g. a "research" session and a "strategy" session on the same laptop — install per-project instead:
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
cd path/to/your/project
|
|
241
|
+
SYM_NODE_NAME=claude-myproject-win npx @sym-bot/mesh-channel init --project
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
This writes `<project>/.mcp.json` and merges `<project>/.claude/settings.local.json` instead of touching `~/.claude.json`. Claude Code loads project-scoped `.mcp.json` on launch and those entries override the global one when you're running from that directory, so each project gets its own `SYM_NODE_NAME` without stepping on siblings.
|
|
245
|
+
|
|
246
|
+
Normal one-machine-one-peer usage does **not** need `--project`.
|
|
247
|
+
|
|
248
|
+
## Cross-network setup (own-hosted relay)
|
|
249
|
+
|
|
250
|
+
LAN-only is enough for two people sitting next to each other. To connect across networks without relying on our hosted relay, run your own:
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
git clone https://github.com/sym-bot/sym-relay
|
|
254
|
+
cd sym-relay && npm install && npm start
|
|
255
|
+
# or deploy the included Dockerfile to Render / Fly / Railway / etc
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Then point peers at the relay inline when joining a group (see [Team mesh groups → Distributed team](#distributed-team-via-relay)) or set the env vars globally in your `claude-sym-mesh` entry in `~/.claude.json`:
|
|
259
|
+
|
|
260
|
+
```json
|
|
261
|
+
"env": {
|
|
262
|
+
"SYM_NODE_NAME": "claude-mac",
|
|
263
|
+
"SYM_RELAY_URL": "wss://your-relay.example.com",
|
|
264
|
+
"SYM_RELAY_TOKEN": "your-shared-token"
|
|
265
|
+
}
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Both peers must use the same relay URL and token to land on the same channel. The relay supports per-token channel isolation so you can run a single relay for multiple groups.
|
|
269
|
+
|
|
270
|
+
## Security
|
|
271
|
+
|
|
272
|
+
Four layers, all must pass before a mesh signal reaches Claude's context:
|
|
273
|
+
|
|
274
|
+
1. **Transport.** Ed25519 peer identity on LAN + relay-token authentication on cross-network. Unauthenticated sources cannot reach `pushChannel()`.
|
|
275
|
+
2. **Protocol.** [SVAF](https://arxiv.org/abs/2604.03955) per-field content gating — evaluates each incoming CMB across 7 semantic dimensions and rejects irrelevant signals before they enter cognitive state.
|
|
276
|
+
3. **Safety.** Prompt-injection filter — pattern-matches every CAT7 field and payload against a curated blocklist of instruction-override, role-hijacking, system-prompt injection, tool-call fabrication, and privilege-escalation patterns. Matched CMBs are blocked and audit-logged to stderr; no silent drops. Per-peer rate limiting (default 30 CMBs/min, configurable via `SYM_RATE_LIMIT`) and a payload size cap (`SYM_MAX_PAYLOAD_BYTES`, default 8 KB) prevent flood and oversized-payload attacks.
|
|
277
|
+
4. **Application.** Text-only context injection, no code execution, no permission relay (`claude/channel/permission` is explicitly not declared).
|
|
278
|
+
|
|
279
|
+
**Optional peer allowlist.** Set `SYM_ALLOWED_PEERS=claude-mac,claude-win` to restrict which authenticated peers can push to Claude's context. When empty (default), all authenticated peers pass layers 1–4.
|
|
280
|
+
|
|
281
|
+
See [SECURITY.md](SECURITY.md) for the full threat model.
|
|
282
|
+
|
|
283
|
+
## Requirements
|
|
284
|
+
|
|
285
|
+
| | macOS | Linux | Windows |
|
|
286
|
+
|---|---|---|---|
|
|
287
|
+
| Node.js ≥ 18 | ✓ | ✓ | ✓ |
|
|
288
|
+
| Claude Code ≥ 2.1.97 (Channels feature) | ✓ | ✓ | ✓ |
|
|
289
|
+
| Bonjour / mDNS for LAN discovery | built-in | install `avahi-daemon` | built-in (Windows 10+) |
|
|
290
|
+
|
|
291
|
+
## Limitations
|
|
292
|
+
|
|
293
|
+
Clear-eyed about what's not there yet:
|
|
294
|
+
|
|
295
|
+
- **Channels still needs a dev flag** for real-time push. The MCP tools work without it; the async push UX does not. Tracking: [anthropics/claude-plugins-official#1512](https://github.com/anthropics/claude-plugins-official/issues/1512).
|
|
296
|
+
- **Corporate networks often block mDNS multicast.** If LAN discovery fails on the same wifi, fall back to a relay.
|
|
297
|
+
- **No offline directory of known groups.** `sym_groups_discover` only shows groups with at least one node currently online. For cross-network relay-backed groups, invite URLs must be shared out of band.
|
|
298
|
+
- **One mesh identity per process.** Two Claude Code sessions on the same machine with the same `SYM_NODE_NAME` will collide — the second one exits with `EIDENTITYLOCK`. Use distinct `SYM_NODE_NAME`s or install per-project (above).
|
|
299
|
+
- **E2E encryption is per-peer-pair, not universal.** CMB field content is encrypted with Curve25519 key agreement + AES-256-GCM between peers that both advertise an E2E public key on handshake. Peers without E2E support fall back to plaintext for backward compatibility. Outer frame metadata (sender ID, timestamp, lineage) stays plaintext — enough for relay forwarding and SVAF evaluation without seeing bodies.
|
|
300
|
+
|
|
301
|
+
## Troubleshooting
|
|
302
|
+
|
|
303
|
+
### `/mcp` reports "Failed to reconnect to claude-sym-mesh"
|
|
304
|
+
|
|
305
|
+
Run the diagnostic:
|
|
306
|
+
|
|
307
|
+
```bash
|
|
308
|
+
npx -y @sym-bot/mesh-channel doctor
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
It lists every `claude-sym-mesh` entry in `~/.claude.json` (user-global plus every project-scope) with `[live]` or `[STALE]` next to each. A stale entry is one whose configured `server.js` path no longer exists on disk — common after moving or reinstalling the repo.
|
|
312
|
+
|
|
313
|
+
Heal every stale entry in one pass:
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
npx -y @sym-bot/mesh-channel init
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
`init` preserves each entry's `SYM_NODE_NAME` so your mesh identity doesn't drift. Live entries are left alone; `--force` is only needed to overwrite a live entry deliberately. Restart Claude Code after healing — MCP servers are spawned at session start and won't pick up config changes mid-session.
|
|
320
|
+
|
|
321
|
+
### Peers connect (Claude Code starts cleanly) but never appear in `sym_peers`
|
|
322
|
+
|
|
323
|
+
Almost always a **mesh group mismatch** — Bonjour scopes discovery by service type (`_<group>._tcp`), so `default` and `backend-team` nodes on the same wifi are invisible to each other. Two diagnostics:
|
|
324
|
+
|
|
325
|
+
```
|
|
326
|
+
> sym_status # shows: Group: <name> (<service-type>)
|
|
327
|
+
> sym_groups_discover # shows every group currently advertising on the LAN
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
If your teammate's node is on a different group, align via `sym_join_group` (this session) and persist via `init --group <name>` (future sessions). Run `npx @sym-bot/mesh-channel doctor` to confirm the persisted group on every entry — the doctor explicitly flags mismatches across user-global and project-scoped configs.
|
|
331
|
+
|
|
332
|
+
This is the failure pattern where every other indicator looks healthy: `sym_status` says `Peers: 0` but the underlying SymNode is fine, the mDNS service is registered, and the relay (if any) is connected — they're just announced on a service type your peer isn't browsing.
|
|
333
|
+
|
|
334
|
+
### Peers don't see each other on the same wifi
|
|
335
|
+
|
|
336
|
+
Check Bonjour is running:
|
|
337
|
+
|
|
338
|
+
- macOS: `dns-sd -B _sym._tcp` (built-in)
|
|
339
|
+
- Linux: `avahi-browse -r _sym._tcp` (needs `avahi-daemon` running)
|
|
340
|
+
- Windows 10+: built-in. If discovery fails, check Windows Firewall allows mDNS (port 5353 UDP).
|
|
341
|
+
|
|
342
|
+
Some corporate networks block mDNS multicast entirely — try a hotspot or home wifi to verify. If LAN is blocked, fall back to a relay.
|
|
343
|
+
|
|
344
|
+
### `<channel>` notifications never arrive even though peers are connected
|
|
345
|
+
|
|
346
|
+
The 11 tools work without any flag. The real-time `<channel>` **push** is separate: Claude Code only delivers channel notifications for channels on its **approved-channels allowlist**, and sym-mesh-channel isn't on it yet — so push requires the development-channels flag matching your install path:
|
|
347
|
+
|
|
348
|
+
- plugin install: `--dangerously-load-development-channels plugin:sym-mesh-channel@claude-community` (or `@sym-mesh-channel` if you installed from the source-repo marketplace — the handle must match your install source)
|
|
349
|
+
- npm install: `--dangerously-load-development-channels server:claude-sym-mesh`
|
|
350
|
+
|
|
351
|
+
This is an Anthropic-side gate, not a bug here — once the channel is allowlisted the flag is no longer needed. Tracked in [anthropics/claude-plugins-official#1512](https://github.com/anthropics/claude-plugins-official/issues/1512).
|
|
352
|
+
|
|
353
|
+
### `sym_status` says "Relay: connected" when you didn't configure one
|
|
354
|
+
|
|
355
|
+
Your shell profile (`~/.zshrc`, `~/.bashrc`) exports `SYM_RELAY_URL`. Claude Code's MCP env block is **additive** — omitting a key doesn't remove it from the child process. Fix: set `SYM_RELAY_URL` and `SYM_RELAY_TOKEN` to `""` in the MCP env block. The installer does this automatically as of v0.1.8.
|
|
356
|
+
|
|
357
|
+
### Multiple Claude Code sessions on the same machine want to share an identity
|
|
358
|
+
|
|
359
|
+
Don't. Each session should have a distinct `SYM_NODE_NAME`. The SymNode acquires an exclusive lockfile on its identity (`~/.sym/nodes/<name>/lock.pid`) and refuses to start a second process with the same name. If you see `EIDENTITYLOCK`, kill the other process or pick a different name. For multiple parallel sessions with their own identities, use the per-project install above.
|
|
360
|
+
|
|
361
|
+
## Other install paths
|
|
362
|
+
|
|
363
|
+
### Via npm (server install)
|
|
364
|
+
|
|
365
|
+
```bash
|
|
366
|
+
npm install -g @sym-bot/mesh-channel
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
Installs the engine globally and exposes it as an MCP server (`server:claude-sym-mesh`). Use this if you prefer npm for install/update management, or want `@sym-bot/sym` available outside the plugin surface. (For real-time push on this path, see [Troubleshooting](#channel-notifications-never-arrive-even-though-peers-are-connected).)
|
|
370
|
+
|
|
371
|
+
## References
|
|
372
|
+
|
|
373
|
+
- [SVAF paper](https://arxiv.org/abs/2604.03955) — Xu, 2026. *Symbolic-Vector Attention Fusion for Collective Intelligence*. arXiv:2604.03955.
|
|
374
|
+
- [MMP paper](https://arxiv.org/abs/2604.19540) — Xu, 2026. *Mesh Memory Protocol: Semantic Infrastructure for Multi-Agent LLM Systems*. arXiv:2604.19540.
|
|
375
|
+
- [MMP spec v1.0](https://meshcognition.org/spec/mmp) — Mesh Memory Protocol specification (canonical web version).
|
|
376
|
+
- [sym-swift](https://github.com/sym-bot/sym-swift) — iOS/macOS SDK implementing the same protocol.
|
|
377
|
+
- [sym-relay](https://github.com/sym-bot/sym-relay) — WebSocket relay for cross-network mesh.
|
|
378
|
+
|
|
379
|
+
## License
|
|
380
|
+
|
|
381
|
+
Apache 2.0 — [SYM.BOT](https://sym.bot).
|