@sym-bot/mesh-channel 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.1.18
+
+### Changed
+
+- **Auto-configure on install.** `npm install -g` now runs `postinstall`
+  that writes the MCP server config to global `mcpServers` in
+  `~/.claude.json` automatically. No separate `sym-mesh-channel init`
+  step needed — two commands to mesh: install + launch.
+- **Global MCP config** — server entry is now written to top-level
+  `mcpServers` (available in all Claude Code sessions), not
+  project-scoped.
+- **Windows postinstall fixes** — `require.resolve` for server.js path
+  (handles npm staging directory on Windows), EBUSY handling when
+  Claude Code has `~/.claude.json` locked, graceful skip if Claude
+  Code not yet installed.
+- **README repositioned** — lead with capability ("first non-Anthropic
+  Claude Code Channels implementation"), not use case. Simplified
+  Quick Start to two commands.
+- **0 vulnerabilities** — fresh dependency rebuild resolves all 6
+  moderate hono/node-server advisories.
+- Windows mDNS: built-in on Windows 10+, no Bonjour install needed.
+
 ## 0.1.7
 
 ### Added

package/README.md

@@ -6,15 +6,20 @@
 [![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.
+> MCP server that turns Claude Code into a peer node on the [SYM mesh](https://sym.bot) — the first non-Anthropic implementation of Claude Code Channels for real-time agent-to-agent cognition.
 
-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 sessions on different machines discover each other via Bonjour mDNS, form a peer-to-peer mesh, and exchange structured cognitive signals in real-time. Each side is a full peer with its own cryptographic identity, its own [SVAF](https://arxiv.org/abs/2604.03955) receiver-side gating, and its own memory — not a thin client. Signals arrive mid-conversation as `<channel>` notifications. No polling, no shared server, no orchestrator.
 
-**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`.
+**Verified cross-platform:** Mac ↔ Windows on the same wifi, pure Bonjour, no relay, no token. Cross-network via optional WebSocket relay.
 
 - **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)
+
+## What this looks like
+
+A Claude Code session on Mac broadcasts a structured signal: `focus: "echo loop between same-domain agents"`, `intent: "need architecture review before implementation"`. A session on Windows receives it in real-time as a `<channel>` notification — no tool call, it just appears mid-conversation. The Windows Claude reviews, responds with a detailed architecture analysis, and the Mac session sees the response land mid-turn. Two agents coordinated through typed cognitive signals on an open protocol, across machines, with zero human copy-paste.
+
+This isn't hypothetical. This README was coordinated by two Claude Code sessions working through the mesh it describes.
 
 ## How real-time push works (Claude Code Channels + MMP)
 
@@ -26,38 +31,24 @@ This MCP server composes two things:
 
 **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:
+## Quick start
 
 ```bash
-# 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 sym-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
-```
-
-Inside Claude Code, verify the mesh:
-
-```
-sym_status   →  Node: claude-mac (...), Relay: disconnected, Peers: 1
-sym_peers    →  1 peer(s): claude-win via bonjour
+npm install -g @sym-bot/mesh-channel    # install + auto-configure ~/.claude.json
+claude --dangerously-load-development-channels server:claude-sym-mesh   # launch
 ```
 
-Then send a message:
+Install auto-detects your hostname, creates a unique node identity, and configures the MCP server globally in `~/.claude.json`. If two people are on the same wifi, their sessions discover each other automatically. Verify inside Claude Code:
 
 ```
-sym_send "hello from Mac"
+sym_status   →  Node: claude-yourhostname, Peers: 1
+sym_peers    →  1 peer(s): claude-theirhostname via bonjour
+sym_send "reviewing the auth module — found a race condition"
 ```
 
-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.
+The other peer sees it arrive **in their Claude Code context as a real-time `<channel>` notification** — no polling, no tool call. It just appears mid-conversation. Their Claude can reason about it, respond, or act on it autonomously.
 
-That's it: cross-machine Claude-to-Claude collective intelligence over a typed cognitive protocol, on the same wifi, in two minutes.
+For cross-network setup (different offices, remote team), see [Cross-network setup](#cross-network-setup-optional) below.
 
 ## Requirements
 
@@ -65,7 +56,7 @@ That's it: cross-machine Claude-to-Claude collective intelligence over a typed c
 |---|---|---|---|
 | 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) |
+| Bonjour / mDNS for LAN discovery | built-in | install `avahi-daemon` | built-in (Windows 10+) |
 
 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.
 

package/bin/install.js

@@ -33,6 +33,7 @@ const os = require('os');
 
 const args = process.argv.slice(2);
 const force = args.includes('--force');
+const isPostinstall = args.includes('--postinstall');
 const cmd = args.find((a) => !a.startsWith('--')) || 'init';
 
 if (cmd !== 'init') {
@@ -52,10 +53,16 @@ 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');
+// Resolve server.js from the installed package location. require.resolve
+// returns the actual installed path regardless of where postinstall runs
+// from (npm on Windows may run postinstall from a temp staging directory).
+let serverJsPath;
+try {
+  serverJsPath = require.resolve('@sym-bot/mesh-channel/server.js');
+} catch {
+  // Fallback for local development / cloned repo
+  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');
@@ -67,6 +74,11 @@ if (!fs.existsSync(serverJsPath)) {
 const claudeJsonPath = path.join(os.homedir(), '.claude.json');
 
 if (!fs.existsSync(claudeJsonPath)) {
+  if (isPostinstall) {
+    // During postinstall, skip silently if Claude Code isn't installed yet
+    console.log('sym-mesh-channel: ~/.claude.json not found — run `sym-mesh-channel init` after installing Claude Code.');
+    process.exit(0);
+  }
   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');
@@ -89,20 +101,21 @@ 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 ────────────────────────
+// ── Find the MCP servers entry to insert into ───────────────────
+// Write to global mcpServers (available in all Claude Code sessions),
+// not project-scoped. A mesh node should be available everywhere.
 
-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 = {};
+if (!claudeJson.mcpServers) claudeJson.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`);
+if (claudeJson.mcpServers['claude-sym-mesh'] && !force) {
+  if (isPostinstall) {
+    // During postinstall, silently skip if already configured
+    console.log('sym-mesh-channel: already configured in ~/.claude.json (skipping)');
+    process.exit(0);
+  }
+  process.stderr.write(`'claude-sym-mesh' is already configured in ~/.claude.json.\n`);
   process.stderr.write('Re-run with --force to overwrite, or remove the existing entry first.\n');
   process.exit(2);
 }
@@ -127,7 +140,7 @@ const entry = {
   },
 };
 
-project.mcpServers['claude-sym-mesh'] = entry;
+claudeJson.mcpServers['claude-sym-mesh'] = entry;
 
 // ── Atomic write ──────────────────────────────────────────────────
 
@@ -143,48 +156,44 @@ try {
 }
 
 const tmpPath = `${claudeJsonPath}.tmp-${process.pid}`;
-fs.writeFileSync(tmpPath, serialized);
-fs.renameSync(tmpPath, claudeJsonPath);
+try {
+  fs.writeFileSync(tmpPath, serialized);
+  fs.renameSync(tmpPath, claudeJsonPath);
+} catch (e) {
+  // EBUSY on Windows when Claude Code has ~/.claude.json locked
+  if (e.code === 'EBUSY' || e.code === 'EPERM') {
+    try { fs.unlinkSync(tmpPath); } catch {}
+    if (isPostinstall) {
+      console.log('sym-mesh-channel: ~/.claude.json is locked (Claude Code may be running).');
+      console.log('Run `sym-mesh-channel init` after quitting Claude Code.');
+      process.exit(0);
+    }
+    process.stderr.write(`ERROR: ${claudeJsonPath} is locked — Claude Code may be running.\n`);
+    process.stderr.write('Quit Claude Code, then re-run: sym-mesh-channel init\n');
+    process.stderr.write(`Backup is at ${backupPath}\n`);
+    process.exit(1);
+  }
+  throw e;
+}
 
 // ── Print next steps ──────────────────────────────────────────────
 
 const launchCmd = `claude --dangerously-load-development-channels server:claude-sym-mesh`;
 
 console.log(`
-✓ sym-mesh-channel installed for project: ${projectDir}
+✓ sym-mesh-channel configured globally in ~/.claude.json
 
   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:
+Launch Claude Code with the Channels flag:
 
-       sym_send "hello mesh"
+  ${launchCmd}
 
-     The other peer should see it land in their Claude Code context
-     as a real-time channel notification — no polling.
+Inside Claude Code, verify:
 
-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).
+  sym_status   →  node id, relay state, peer count
+  sym_peers    →  discovered peers via Bonjour or relay
+  sym_send "hello mesh"   →  broadcast to all peers
 `);

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@sym-bot/mesh-channel",
-  "version": "0.1.17",
-  "description": "MCP server — Claude Code as a peer node on the SYM mesh. LAN-first via Bonjour, no relay required.",
+  "version": "0.1.18",
+  "description": "MCP server — real-time agent-to-agent cognition for Claude Code remote teams via the SYM mesh.",
   "main": "server.js",
   "bin": {
     "sym-mesh-channel": "server.js"
   },
+  "scripts": {
+    "postinstall": "node bin/install.js init --postinstall"
+  },
   "files": [
     "server.js",
     "bin/",