Sym Mesh Channel

sym-mesh-channel

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).

> 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.

# in Claude Code — the first line is one-time setup
/plugin marketplace add sym-bot/marketplace
/plugin install sym-mesh-channel@sym-bot

[](https://www.npmjs.com/package/@sym-bot/mesh-channel) [](https://github.com/anthropics/claude-plugins-community) [](https://meshcognition.org/spec/mmp) [](https://arxiv.org/abs/2604.03955) [](https://arxiv.org/abs/2604.19540) [](LICENSE) [](https://nodejs.org) [](README_zh.md)

---

What it actually looks like

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:

🖥️ melotune-dev finds the crash, commits the fix, and pings the CTO session for clearance — then receives the all-clear and ships:

🖥️ 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:

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.

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.

> ⚠️ 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).

Who this is for

• 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.
• Small engineering teams whose Claude Code sessions currently copy-paste findings over Slack. Replace that loop with direct agent-to-agent coordination.
• Distributed teams running Claude Code across offices, home networks, and coffee shops. Isolated team channels via mesh groups, no shared server.
• Multi-agent developers prototyping cognitive architectures — sym-mesh-channel is the reference Claude Code host for the Mesh Memory Protocol.
• 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.

Where this sits — built on sym

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, the universal CLI + library, and speaks the same open MMP protocol and SVAF relevance gate.

@sym-bot/mesh-channel   this package · Claude-Code-native · real-time push ()
        ▼ depends on
@sym-bot/sym            the CLI · any agent, any language · sym ask (pull)

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.

Which do you install?

• 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.
• Other agents (Cursor, Copilot), scripts, any language — or you want the sym ask CLI in your terminal? → @sym-bot/sym + the skill file per agent.

Quick start

One command — it configures the mesh and launches Claude Code with real-time push already on:

npx @sym-bot/mesh-channel@latest start

Run it in any repo, in as many terminals as you like — the sessions discover each other over loopback (or the same wifi) and think together in real time. No flag to remember, no plugin: vs server: to choose — start wires the channel for you. (First run configures the MCP server; after that it just launches. Co-resident sessions don't collide — each becomes its own peer.)

Stand up a persistent named agent, or join a team room:

npx @sym-bot/mesh-channel@latest start --name cto --group my-team

(start --print shows the exact claude … command without launching; anything after -- is passed straight to claude, e.g. … start -- --resume.)

Prefer the Claude Code plugin UI?

Install the plugin and you get the 11 MCP tools immediately:

/plugin marketplace add sym-bot/marketplace
/plugin install sym-mesh-channel@sym-bot

For real-time push on this path, launch with the channel flag (the handle must match where you installed from):

claude --dangerously-load-development-channels plugin:sym-mesh-channel@sym-bot

Also listed in the Anthropic community directory as sym-mesh-channel@claude-community — but that listing can lag behind releases, so install from @sym-bot above for the current build.

> The dev flag is temporary — an Anthropic-side gate while the channel awaits the approved-channels allowlist (anthropics/claude-plugins-official#1512). start passes it under the hood today; once the channel is allowlisted it disappears. Curious when to use the npm/server install directly (named agents, repo-committed team config, the sym CLI)? See [Advanced](#advanced-named-agents-teams--the-cli).

What you get

Eleven MCP tools exposed to Claude Code, namespaced under mcp__claude-sym-mesh__:

| Tool | What it does | |---|---| | sym_send | Send a CAT7 CMB to a specific peer (point-to-point), or to all if no recipient is given. Arrives in receivers' contexts as a ` notification. | | sympublish | Publish a structured CAT7 CMB — a projection of your state — to your whole group (publish-subscribe): focus, issue, intent, motivation, commitment, perspective, mood. SVAF-gated on the receiving side. | | symreceive | Surface CMBs the mesh delivered to you in real-time when the push was gated — a live delivery feed, not a store query. | | symrecall | Search mesh memory for past cognitive memory blocks. | | symfetch | Fetch the full content of a single CMB by its compact channel-header ID. | | sympeers | List discovered peers (via bonjour or relay). | | symstatus | Node identity, relay state, peer count, memory count, current mesh group. | | symgroupinfo | Report the mesh group this node is in, with service type and peer roster scoped to the group. | | syminvitecreate | Generate a shareable invite URL for a named group. LAN-only or cross-network flavour. | | syminviteinfo | Parse a mesh invite URL and return a ready-to-use symjoingroup call. | | symjoingroup | **Hot-swap** this node into a different mesh group at runtime — no Claude Code restart. | | symgroupsdiscover` | List SYM-mesh groups currently advertising on the local network via Bonjour / mDNS. |

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.

Team mesh groups

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.

> 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'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.)

Same office (LAN)

Team lead creates the group from any Claude Code session:

> sym_invite_create { "group": "backend-team" }

Invite URL (LAN-only (Bonjour)):
    sym://group/backend-team

> sym_join_group { "group": "backend-team" }
Hot-swapped from group "default" (_sym._tcp) to "backend-team" (_backend-team._tcp).

Team lead shares the URL over Slack, email, whatever.

Each teammate pastes the URL into their Claude Code session:

> sym_invite_info { "url": "sym://group/backend-team" }
Parsed invite: sym://group/backend-team

> sym_join_group { "group": "backend-team" }
Hot-swapped from group "default" to "backend-team".

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.

> 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).

Persisting your group across restarts

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:

# (a) Reinstall with the --group flag — preserves SYM_NODE_NAME from the
#     existing entry, adds SYM_GROUP, atomically rewrites ~/.claude.json:
npx @sym-bot/mesh-channel init --force --group backend-team

# (b) For a project-scoped install (multi-project laptop):
cd path/to/project
SYM_NODE_NAME=claude-myproject npx @sym-bot/mesh-channel init --project --group backend-team

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:

# Switch from one named group to another (one command):
npx @sym-bot/mesh-channel init --force --group new-team

# Revert to the global mesh (escape hatch):
npx @sym-bot/mesh-channel init --force --group default

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.

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".

Distributed team (via relay)

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 repo.

> sym_invite_create {
    "group": "eng-team",
    "relay_url": "wss://sym-relay.onrender.com",
    "relay_token": "any-shared-secret-the-team-agrees-on"
  }

Invite URL (cross-network (relay)):
    sym://team/eng-team?relay=wss%3A%2F%2Fsym-relay.onrender.com&token=any-shared-secret-...

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.

Discovering what's out there

> sym_groups_discover

SYM-mesh groups visible on LAN (3):
  _sym._tcp           group="sym"
  _backend-team._tcp  group="backend-team"   (← your current group)
  _frontend-team._tcp group="frontend-team"

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).

How it works

Claude Code A                                              Claude Code B
     ↕ (stdio + MCP)                                            ↕
sym-mesh-channel  ←——  Bonjour mDNS  ——→  sym-mesh-channel
     ↕                  (LAN discovery)                         ↕
     └────────────  optional WebSocket relay  ───────────────┘
                    (cross-network)

The plugin composes two open specs:

• Claude Code Channels (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.
• MMP — the Mesh Memory Protocol — defines what gets pushed: typed seven-field cognitive bundles (CAT7: focus, issue, intent, motivation, commitment, perspective, mood), how receivers gate incoming signals (SVAF), and how peers maintain identity without a central orchestrator.

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 ` block in the conversation. Claude sees it, can react, and can broadcast back via symsend or sympublish`. No polling. No tool calls. The mesh thinks together.

Identity and transport. Each peer has its own Ed25519 keypair stored at ~/.sym/nodes//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.

Advanced: per-project node identity

By default each session picks up an identity automatically — fine for one-machine, one-peer use. Override it when you want a project to appear as a stable, named peer every time: a cto session and a melotune-dev session on the same laptop, each keeping its name (and team group) across restarts instead of an auto-generated claude-- that changes per session.

Commit a .sym/node.json to the project — e.g. path/to/project/.sym/node.json:

{
  "node_name": "cto",
  "group": "my-team"
}

The plugin reads it on launch (v0.3.22+) whenever Claude Code runs from that director

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sym-bot
• Source: sym-bot/sym-mesh-channel
• License: Apache-2.0
• Homepage: https://sym.bot

Install and usage instructions live in the source repository linked above.