@sym-bot/mesh-channel 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.1.7
+
+### Added
+
+- **`npx @sym-bot/mesh-channel init`** — interactive installer that
+  writes `~/.claude.json` for the current project, picks a sensible
+  default `SYM_NODE_NAME` (`claude-mac` / `claude-win` / `claude-linux`),
+  resolves the absolute path to `server.js`, and prints the launch
+  command including the `--dangerously-load-development-channels` flag.
+  Backs up the existing config to `~/.claude.json.bak-<timestamp>`,
+  validates JSON round-trip, atomic write via tmp+rename. Refuses to
+  overwrite an existing entry without `--force`.
+- **README rewritten for LAN-first install.** Quick start is two
+  minutes: install, init, launch. No relay required. Bonjour/mDNS
+  is the default discovery path. Cross-network setup (relay) is now
+  the optional advanced section.
+
+### Changed
+
+- `package.json` `bin` now exposes both `sym-mesh-channel` (server
+  entrypoint) and `sym-mesh-channel-init` (installer). The package
+  description leads with "LAN-first via Bonjour, no relay required."
+
+### Why
+
+The 0.1.5/0.1.6 install path required users to manually edit
+`~/.claude.json`, know about the Channels dev flag, set up a relay,
+and obtain a relay token. That gated the demo behind real friction.
+LAN-only mode has worked since day one in the underlying SymNode
+(`sym/lib/node.js:509-511` only connects to the relay if `SYM_RELAY_URL`
+is set; Bonjour discovery starts unconditionally), but no documentation
+or installer surfaced it. This release closes that gap: two users on
+the same wifi can join the same mesh in two minutes with three commands.
+
 ## 0.1.6
 
 ### Fixed

package/README.md

@@ -1,69 +1,122 @@
 # sym-mesh-channel
 
-MCP server that makes Claude Code a peer node on the [SYM mesh](https://sym.bot).
+[![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)
 
-This is a **peer node**, not a client. It has its own identity, its own relay connection, and its own SVAF evaluation with domain-specific field weights.
+> 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.
 
-## Setup
+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.
 
-### 1. Install
+This is the reference implementation of MMP (the Mesh Memory Protocol) for Claude Code hosts. See:
+
+- **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)
+
+## Quick start (LAN, two minutes)
+
+You and one other person on the same wifi each run:
 
 ```bash
-git clone https://github.com/sym-bot/sym-mesh-channel.git
-cd sym-mesh-channel
-npm install
+# 1. Install
+npm install -g @sym-bot/mesh-channel
+
+# 2. Configure Claude Code (writes ~/.claude.json for the current project)
+SYM_NODE_NAME=claude-mac npx @sym-bot/mesh-channel init
+#                ^^^^^^ pick a unique name per machine: claude-mac, claude-win, claude-linux, anything
+
+# 3. Launch Claude Code with the Channels dev flag
+claude --dangerously-load-development-channels server:claude-sym-mesh
 ```
 
-### 2. Configure Claude Code
+Inside Claude Code, ask it:
 
-Add to `~/.claude/mcp.json` (macOS/Linux) or `%USERPROFILE%\.claude\mcp.json` (Windows):
+> verify the mesh: run sym_status and sym_peers, then sym_send "hello"
 
-```json
-{
-  "mcpServers": {
-    "sym-mesh-channel": {
-      "command": "node",
-      "args": ["/absolute/path/to/sym-mesh-channel/server.js"],
-      "env": {
-        "SYM_RELAY_URL": "wss://your-relay-url",
-        "SYM_RELAY_TOKEN": "your-token",
-        "SYM_NODE_NAME": "claude-code-mac"
-      }
-    }
-  }
-}
-```
+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.
+
+## Requirements
+
+| | macOS | Linux | Windows |
+|---|---|---|---|
+| Node.js ≥ 18 | ✓ | ✓ | ✓ |
+| Claude Code ≥ 2.1.97 (Channels feature) | ✓ | ✓ | ✓ |
+| Bonjour / mDNS for LAN discovery | built-in | install `avahi-daemon` | install [Bonjour for Windows](https://support.apple.com/kb/DL999) (ships with iTunes) |
 
-`SYM_NODE_NAME` sets the node's identity on the mesh. Use platform-scoped names (`claude-code-mac`, `claude-code-win`) when running the same role on multiple devices, per MMP §3.1.2. Defaults to `claude-code-mac` if unset.
+The `--dangerously-load-development-channels` flag is required because this MCP server is not yet on Anthropic's public Channels allowlist. The flag opts your local Claude Code into receiving `notifications/claude/channel` from a non-allowlisted MCP server. Without it, the MCP loads but real-time push is silently dropped.
 
-### 3. Restart Claude Code
+## What you get
 
-The MCP server loads on startup. Run `/mcp` to verify connection.
+Five MCP tools exposed to Claude Code, namespaced under `mcp__claude-sym-mesh__`:
 
-## Tools
+| Tool | What it does |
+|---|---|
+| `sym_send` | Broadcast a free-text message to all mesh peers. Arrives in receivers' contexts as a `<channel>` notification. |
+| `sym_observe` | Share a structured CAT7 observation: focus, issue, intent, motivation, commitment, perspective, mood. SVAF-gated on the receiving side. |
+| `sym_recall` | Search mesh memory for past CMBs. |
+| `sym_peers` | List discovered peers (via bonjour or relay). |
+| `sym_status` | Node identity, relay state, peer count, memory count. |
 
-| Tool | Description |
-|------|-------------|
-| `sym_send` | Broadcast a message to all mesh peers |
-| `sym_observe` | Share a structured CAT7 observation |
-| `sym_recall` | Search mesh memory |
-| `sym_peers` | List connected peers |
-| `sym_status` | Node status — relay, peers, memory count |
+Real-time push is bidirectional: peer events arrive in Claude's context without any tool call, while the session is mid-turn. This is the "Claude thinks with the mesh" property — not "Claude pokes the mesh occasionally."
 
-## Architecture
+## How it works
 
 ```
-Claude Code ←stdio→ sym-mesh-channel (SymNode) ←wss→ relay ←wss→ other peers
+Claude Code A                                              Claude Code B
+     ↕ (stdio + MCP)                                            ↕
+sym-mesh-channel (SymNode)  ←—  Bonjour mDNS  —→  sym-mesh-channel (SymNode)
+     ↕                          (LAN discovery)                 ↕
+     └────────────  optional WebSocket relay  ────────────────┘
+                    (cross-network, see below)
 ```
 
-- **Outbound**: Claude Code calls MCP tools → SymNode sends to mesh
-- **Inbound**: Mesh events → SymNode → MCP channel notifications → Claude Code
+- **Stdio half**: Claude Code spawns the MCP server as a child process. MCP tool calls flow over stdio.
+- **Push half**: when a CMB arrives at the SymNode (via Bonjour or relay), the MCP server fires a `notifications/claude/channel` notification back over stdio. Claude Code surfaces it as a `<channel>` block in the conversation context.
+- **Identity**: each peer has its own Ed25519 keypair stored at `~/.sym/nodes/<name>/identity.json`. NodeIDs are UUID v7 + Ed25519 signatures, gossiped through the relay's directory and/or via Bonjour TXT records.
+- **SVAF**: incoming CMBs are evaluated by Symbolic-Vector Attention Fusion before they enter cognitive state. Low-relevance CMBs are gated out so the receiver's context doesn't drown.
 
-## Requirements
+For the full architecture, see MMP spec sections 4-6.
+
+## Cross-network setup (optional)
+
+LAN-only is enough for two people sitting next to each other. To connect across networks (different offices, coffee shop ↔ home, etc.) you need a relay:
+
+```bash
+# Run your own relay (Render-friendly Dockerfile included)
+git clone https://github.com/sym-bot/sym-relay
+cd sym-relay && npm install && npm start
+# or deploy the Dockerfile to Render / Fly / Railway / etc
+```
+
+Then add the relay env vars to your `claude-sym-mesh` entry in `~/.claude.json`:
+
+```json
+"env": {
+  "SYM_NODE_NAME": "claude-mac",
+  "SYM_RELAY_URL": "wss://your-relay.example.com",
+  "SYM_RELAY_TOKEN": "your-shared-token"
+}
+```
+
+Both peers must use the same relay URL and token to be on the same channel. The relay supports per-token channel isolation so you can run a single relay for multiple groups.
+
+## Troubleshooting
+
+**Peers don't see each other on the same wifi.** Check Bonjour is running:
+- macOS: `dns-sd -B _sym._tcp` (built-in)
+- Linux: `avahi-browse -r _sym._tcp` (needs `avahi-daemon` running)
+- Windows: ensure Bonjour Print Services or iTunes-bundled Bonjour is installed; check Services → Bonjour Service is running
+
+Some corporate networks block mDNS multicast — try a hotspot or home wifi to verify. If LAN is blocked, fall back to a relay.
+
+**`<channel>` notifications never arrive even though peers are connected.** Verify Claude Code was launched with `--dangerously-load-development-channels server:claude-sym-mesh`. Without that exact flag, MCP push notifications are silently dropped.
+
+**`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.
 
-- Node.js >= 18
-- Claude Code with MCP support
-- A SYM relay server (see [sym-relay](https://github.com/sym-bot/sym-relay))
+**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

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * sym-mesh-channel install — interactive setup for the MCP server.
+ *
+ * Run: npx @sym-bot/mesh-channel init
+ *
+ * What it does:
+ *   1. Detects the platform and the host name suggestion (claude-mac /
+ *      claude-win / claude-linux), or accepts an override.
+ *   2. Resolves the absolute path to the installed server.js so Claude
+ *      Code can spawn it.
+ *   3. Reads ~/.claude.json (the Claude Code settings file), backs it
+ *      up, adds an `mcpServers` entry under the current project for
+ *      `claude-sym-mesh`, atomically writes the result.
+ *   4. Prints the launch command including the Channels dev flag.
+ *
+ * Safety:
+ *   - Backs up ~/.claude.json to ~/.claude.json.bak-<timestamp> before
+ *     any write.
+ *   - Validates JSON parses round-trip before writing.
+ *   - Atomic via write-to-tmp + rename.
+ *   - Refuses to overwrite an existing claude-sym-mesh entry without
+ *     --force.
+ *
+ * Copyright (c) 2026 SYM.BOT Ltd. Apache 2.0 License.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const args = process.argv.slice(2);
+const force = args.includes('--force');
+const cmd = args.find((a) => !a.startsWith('--')) || 'init';
+
+if (cmd !== 'init') {
+  process.stderr.write(`Unknown command: ${cmd}\nUsage: npx @sym-bot/mesh-channel init [--force]\n`);
+  process.exit(1);
+}
+
+// ── Detect platform & defaults ────────────────────────────────────
+
+const platform = process.platform;
+const platformSuffix = platform === 'darwin' ? 'mac' : platform === 'win32' ? 'win' : 'linux';
+const defaultNodeName = `claude-${platformSuffix}`;
+
+// SYM_NODE_NAME from env wins over default
+const nodeName = process.env.SYM_NODE_NAME || defaultNodeName;
+
+// ── Resolve server.js path ────────────────────────────────────────
+
+// __dirname is .../node_modules/@sym-bot/mesh-channel/bin in npm install,
+// or .../sym-mesh-channel/bin if running from a clone. server.js is one
+// level up either way.
+const serverJsPath = path.resolve(__dirname, '..', 'server.js');
+if (!fs.existsSync(serverJsPath)) {
+  process.stderr.write(`ERROR: cannot find server.js at ${serverJsPath}\n`);
+  process.stderr.write('This installer must be run from a published @sym-bot/mesh-channel package.\n');
+  process.exit(1);
+}
+
+// ── Locate Claude Code settings file ──────────────────────────────
+
+const claudeJsonPath = path.join(os.homedir(), '.claude.json');
+
+if (!fs.existsSync(claudeJsonPath)) {
+  process.stderr.write(`ERROR: ${claudeJsonPath} not found.\n`);
+  process.stderr.write('Claude Code does not appear to be installed (or has not been launched yet).\n');
+  process.stderr.write('Install Claude Code from https://claude.com/code first, launch it once, then re-run this installer.\n');
+  process.exit(1);
+}
+
+// ── Read and back up ──────────────────────────────────────────────
+
+let claudeJson;
+try {
+  const raw = fs.readFileSync(claudeJsonPath, 'utf8');
+  claudeJson = JSON.parse(raw);
+} catch (e) {
+  process.stderr.write(`ERROR: ${claudeJsonPath} is not valid JSON: ${e.message}\n`);
+  process.stderr.write('Refusing to overwrite a corrupt Claude Code settings file.\n');
+  process.exit(1);
+}
+
+const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+const backupPath = `${claudeJsonPath}.bak-${ts}`;
+fs.copyFileSync(claudeJsonPath, backupPath);
+
+// ── Find the project entry to insert into ────────────────────────
+
+const projectDir = process.cwd();
+if (!claudeJson.projects) claudeJson.projects = {};
+if (!claudeJson.projects[projectDir]) {
+  claudeJson.projects[projectDir] = {};
+}
+const project = claudeJson.projects[projectDir];
+if (!project.mcpServers) project.mcpServers = {};
+
+// ── Refuse to overwrite without --force ──────────────────────────
+
+if (project.mcpServers['claude-sym-mesh'] && !force) {
+  process.stderr.write(`'claude-sym-mesh' is already configured for this project (${projectDir}).\n`);
+  process.stderr.write('Re-run with --force to overwrite, or remove the existing entry first.\n');
+  process.exit(2);
+}
+
+// ── Build the entry ───────────────────────────────────────────────
+
+const entry = {
+  command: 'node',
+  args: [serverJsPath],
+  env: {
+    SYM_NODE_NAME: nodeName,
+    // 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: '',
+  },
+};
+
+project.mcpServers['claude-sym-mesh'] = entry;
+
+// ── Atomic write ──────────────────────────────────────────────────
+
+const serialized = JSON.stringify(claudeJson, null, 2);
+
+// Validate round-trip parses
+try {
+  JSON.parse(serialized);
+} catch (e) {
+  process.stderr.write(`ERROR: serialization produced invalid JSON: ${e.message}\n`);
+  process.stderr.write(`Backup is at ${backupPath} — your original file is unchanged.\n`);
+  process.exit(1);
+}
+
+const tmpPath = `${claudeJsonPath}.tmp-${process.pid}`;
+fs.writeFileSync(tmpPath, serialized);
+fs.renameSync(tmpPath, claudeJsonPath);
+
+// ── Print next steps ──────────────────────────────────────────────
+
+const launchCmd = `claude --dangerously-load-development-channels server:claude-sym-mesh`;
+
+console.log(`
+✓ sym-mesh-channel installed for project: ${projectDir}
+
+  Node name:     ${nodeName}
+  Server path:   ${serverJsPath}
+  Backup:        ${backupPath}
+
+Next steps:
+
+  1. Launch Claude Code from this directory with the Channels flag:
+
+     ${launchCmd}
+
+     The flag is required because this MCP server is not yet on
+     Anthropic's public Channels allowlist. Without the flag, the
+     MCP loads but inbound real-time push notifications are silently
+     dropped.
+
+  2. Inside Claude Code, verify the mesh is up:
+
+       sym_status   →  shows your node id, relay state, peer count
+       sym_peers    →  lists discovered peers via Bonjour or relay
+
+  3. Have a friend on the same wifi run the same install with a
+     different SYM_NODE_NAME (e.g. claude-mac vs claude-win). Within
+     a few seconds you should see each other in sym_peers.
+
+  4. Send a message:
+
+       sym_send "hello mesh"
+
+     The other peer should see it land in their Claude Code context
+     as a real-time channel notification — no polling.
+
+LAN-only mode is the default. To connect across networks, add
+SYM_RELAY_URL and SYM_RELAY_TOKEN to the env block in
+${claudeJsonPath} (see README for relay setup).
+`);

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@sym-bot/mesh-channel",
-  "version": "0.1.6",
-  "description": "MCP server — Claude Code as a peer node on the SYM mesh",
+  "version": "0.1.8",
+  "description": "MCP server — Claude Code as a peer node on the SYM mesh. LAN-first via Bonjour, no relay required.",
   "main": "server.js",
   "bin": {
-    "sym-mesh-channel": "server.js"
+    "sym-mesh-channel": "server.js",
+    "sym-mesh-channel-init": "bin/install.js"
   },
   "files": [
     "server.js",
+    "bin/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"