@sym-bot/mesh-channel 0.1.7 → 0.1.9

package/README.md

@@ -1,15 +1,31 @@
 # sym-mesh-channel
 
+[![npm](https://img.shields.io/npm/v/@sym-bot/mesh-channel)](https://www.npmjs.com/package/@sym-bot/mesh-channel)
+[![MMP Spec](https://img.shields.io/badge/protocol-MMP_v0.2.2-purple)](https://sym.bot/spec/mmp)
+[![arXiv](https://img.shields.io/badge/arXiv-2604.03955-b31b1b.svg)](https://arxiv.org/abs/2604.03955)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org)
+
 > MCP server that turns any Claude Code session into a peer node on the [SYM mesh](https://sym.bot). LAN-first via Bonjour mDNS — no relay required for users on the same wifi.
 
-Two Claude Code instances on the same network discover each other automatically and exchange structured cognitive state in real-time. Each side is a full peer with its own cryptographic identity, its own SVAF receiver-side gating, and its own memory — not a thin client.
+Two Claude Code instances on the same network discover each other automatically and exchange structured cognitive state **in real-time**. Each side is a full peer with its own cryptographic identity, its own SVAF receiver-side gating, and its own memory — not a thin client.
 
-This is the reference implementation of MMP (the Mesh Memory Protocol) for Claude Code hosts. See:
+**Verified cross-platform:** Mac ↔ Windows on the same wifi, pure Bonjour, no relay, no token. Bidirectional real-time push confirmed 2026-04-09 with `@sym-bot/sym 0.3.74`.
 
 - **SVAF paper**: [arxiv.org/abs/2604.03955](https://arxiv.org/abs/2604.03955)
 - **MMP spec**: [sym.bot/spec/mmp](https://sym.bot/spec/mmp)
 - **Source**: [github.com/sym-bot/sym-mesh-channel](https://github.com/sym-bot/sym-mesh-channel)
 
+## How real-time push works (Claude Code Channels + MMP)
+
+This MCP server composes two things:
+
+**[Claude Code Channels](https://code.claude.com/docs/en/mcp)** (Anthropic, shipped 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.
+
+**[MMP — the Mesh Memory Protocol](https://sym.bot/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. MMP is the protocol; this MCP server is the reference implementation for Claude Code hosts.
+
+**The composition:** when a peer on the mesh broadcasts a CMB (Cognitive Memory Block), the SymNode inside this MCP evaluates it via SVAF. If accepted, the MCP 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.
+
 ## Quick start (LAN, two minutes)
 
 You and one other person on the same wifi each run:
@@ -26,11 +42,22 @@ SYM_NODE_NAME=claude-mac npx @sym-bot/mesh-channel init
 claude --dangerously-load-development-channels server:claude-sym-mesh
 ```
 
-Inside Claude Code, ask it:
+Inside Claude Code, verify the mesh:
+
+```
+sym_status   →  Node: claude-mac (...), Relay: disconnected, Peers: 1
+sym_peers    →  1 peer(s): claude-win via bonjour
+```
+
+Then send a message:
 
-> verify the mesh: run sym_status and sym_peers, then sym_send "hello"
+```
+sym_send "hello from Mac"
+```
+
+The other peer sees it arrive **in their Claude Code context as a real-time `<channel>` notification** — no polling, no `sym_recall`, no tool call. It just appears. They reply with `sym_send "hello from Windows"` and you see it land in your context the same way.
 
-Within a few seconds the other peer should see your message arrive in their Claude Code context as a real-time `<channel>` notification — no polling, no `sym_recall`. That's it: cross-machine Claude-to-Claude collective intelligence over a typed cognitive protocol.
+That's it: cross-machine Claude-to-Claude collective intelligence over a typed cognitive protocol, on the same wifi, in two minutes.
 
 ## Requirements
 
@@ -110,6 +137,8 @@ Some corporate networks block mDNS multicast — try a hotspot or home wifi to v
 
 **`sym_status` says "Peers: 0" but `sym_peers` lists peers.** Snapshot timing — both views read the same `_peers` map at slightly different moments. The peer set is dynamic. If counts disagree consistently, file an issue.
 
+**`sym_status` says "Relay: connected" even though you didn't configure a relay.** Your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) 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 `""` (empty string) in the MCP env block to override the shell. The installer (`npx @sym-bot/mesh-channel init`) does this automatically as of v0.1.8.
+
 **Multiple Claude Code sessions on the same machine want to share an identity.** Don't. Each session should have a distinct `SYM_NODE_NAME`. As of `@sym-bot/sym 0.3.70`, 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`, find and kill the other process or pick a different name.
 
 ## License

package/bin/install.js

@@ -113,11 +113,16 @@ const entry = {
   args: [serverJsPath],
   env: {
     SYM_NODE_NAME: nodeName,
-    // Relay env vars are intentionally NOT set by default. Without
-    // them, the SymNode runs in LAN-only mode and discovers other
-    // peers via Bonjour mDNS. To enable cross-network connectivity,
-    // add SYM_RELAY_URL and SYM_RELAY_TOKEN to this env block manually
-    // (see README for details on running your own relay).
+    // Explicitly blank the relay vars so the MCP doesn't inherit them
+    // from the parent shell (e.g. ~/.zshrc exports). Claude Code's env
+    // block is ADDITIVE — omitting a key doesn't remove it from the
+    // child process. Setting to '' makes process.env.SYM_RELAY_URL
+    // falsy in JS, so the SymNode skips the relay and runs LAN-only.
+    //
+    // To enable cross-network connectivity later, replace these empty
+    // values with your relay URL and token (see README).
+    SYM_RELAY_URL: '',
+    SYM_RELAY_TOKEN: '',
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sym-bot/mesh-channel",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "MCP server — Claude Code as a peer node on the SYM mesh. LAN-first via Bonjour, no relay required.",
   "main": "server.js",
   "bin": {
@@ -15,8 +15,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@sym-bot/sym": "^0.3.70",
-    "@modelcontextprotocol/sdk": "^1.12.1"
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@sym-bot/sym": "^0.3.74"
   },
   "engines": {
     "node": ">=18"