🧠 Synapse

Real-time multi-agent coordination platform for Claude Code

WebSocket message bus · MCP Channel server · Discord-style management dashboard

Run multiple Claude Code instances on the same codebase. Have them talk to each other, share build & QA results, and coordinate edits — without stepping on each other's commits.

---

🤔 Why this exists

Running 2-4 Claude Code agents in parallel on the same repo is a real dev-velocity unlock — until two of them edit the same file, ship conflicting commits, or step on each other's branches. Synapse is what I built to make that workable: a real-time message bus and coordination layer specifically for fleets of Claude Code agents.

It does three things existing tools don't:

• 🪝 Pushes server-originated messages directly into a running Claude Code conversation — a novel inversion of the standard MCP request/response model. See The Channel pattern below.
• 🔒 File-locking primitive with 30-min auto-expiring locks, consulted by a pre-edit hook before every Write/Edit, so concurrent agents never race on the same file.
• 📡 Activity feed + alerts + auto-checkpoints — every edit, commit, lock, build, and QA result streams to a Discord-style web dashboard in <100ms.

---

🧩 The Channel pattern

This is the bit that makes Synapse genuinely different.

Every existing MCP server today follows a pull model — Claude calls a tool, the server responds. Synapse adds a push channel:

┌─────────────────────────────────┐         ┌─────────────────────────────────┐
│  Synapse Server                 │         │  Bot A (Claude Code instance)   │
│  (Express + WebSocket)          │ ──push──▶│  ┌──────────────────────────┐  │
│                                 │   <chan> │  │  Channel MCP Server      │  │
│  Activity feed · File locks     │   tag    │  │  Injects <channel> tags  │  │
│  Message bus · Alerts           │   into   │  │  into the conversation   │  │
│  Build / QA results             │   conv   │  └──────────────────────────┘  │
└─────────────────────────────────┘          └─────────────────────────────────┘
                ▲
                │ (also handles standard pull-style MCP calls
                │  for file locks, alerts, activity log queries)
                │
   ┌────────────┼────────────┐
   ▼            ▼            ▼
 Bot B        Bot C        Bot D

When Bot A makes an edit, Synapse pushes an update to every other bot's running Claude Code conversation as a <channel> tag — they see what their teammates are doing in near-real-time, without polling, without context bloat. Server-to-client MCP is the open invitation Synapse takes that nobody else is using yet.

---

🏗️ Architecture

┌──────────────────────────────────────┐
│         Synapse Server               │
│      (Express + WebSocket)           │
│                                      │
│  File Locking · Activity Feed        │
│  Message Bus · Alerts · Health       │
└──────────┬───────────────────────────┘
           │ WebSocket + HTTP
     ┌─────┼─────┐
     ▼     ▼     ▼
   Bot A  Bot B  Bot C
   (MCP Channel Servers · pre-edit hooks · auto-checkpoint)

Component	Path	Role
🛰️ Server	server/	Express + WebSocket coordination hub. Tracks bots, locks, activity, messages, alerts, builds, QA results.
📺 Channel	channel/	MCP Channel server — pushes server-originated messages into a running Claude Code conversation as <channel> tags.
🛠️ MCP	mcp/	Standard pull-style MCP tools — file locking, alerts, activity-log queries, message send/recv.
🪝 Hooks	hooks/	Claude Code hooks — pre-edit-check.js, post-sync.js, auto-checkpoint.js, session check-in/out.
🖥️ Dashboard	dashboard/	Single-file Discord-style web UI. No build step, no framework.
📚 Docs	docs/	Setup guides, architecture deep-dives, whitepaper.

---

🚀 Quick Start

# 1️⃣ Configure
cp .env.example .env             # set DEV_SYNC_KEY at minimum (openssl rand -hex 32)
cp users.example.json users.json # edit with your team's Discord IDs (optional)
cd server && npm install

# 2️⃣ Start the server
node server.js
# → Synapse listening on :4100

# 3️⃣ Add the MCP servers to a Claude Code instance
claude mcp add synapse-tools -- node /path/to/Synapse/mcp/index.js \
  --url http://localhost:4100 \
  --developer alice \
  --key your-dev-sync-key

# 4️⃣ Launch Claude Code with the channel attached
claude --dangerously-load-development-channels server:synapse-channel

You'll see your bot register on the dashboard at http://localhost:4100. Run two more Claude Code instances with different --developer slugs and they'll start coordinating immediately.

---

⚙️ Configuration

Synapse separates code from your team's identity data. Two files drive everything:

.env — server config

Copy .env.example to .env. Only DEV_SYNC_KEY is required to run.

Variable	Purpose
DEV_SYNC_KEY	Required. Shared secret every connecting client passes via ?key= or X-Dev-Key.
DISCORD_WEBHOOK_URL	Outbound mirror — relay messages from code / all / direct channels into your Discord.
DISCORD_BOT_TOKEN	Inbound relay — listen to your Discord channels and forward into Synapse.
DISCORD_RELAY_CHANNELS	Comma-separated Discord channel IDs the inbound relay watches.
DISCORD_BEN_WEBHOOK_IDS	Webhook IDs to attribute to the primary user (e.g. external app posting on your behalf).
SYNAPSE_USERS_FILE	Path to users.json. Defaults to ../users.json from the server directory.
SYNAPSE_PUBLIC_URL	Public dashboard URL used in outbound Discord notifications.
SYNAPSE_PROJECT_NAME	Used by hooks to strip absolute paths down to project-relative for display.
GH_REPO	org/repo slug for the GitHub-activity dashboard widget.
SYNAPSE_BACKEND_CLAUDE_MD / SYNAPSE_FRONTEND_CLAUDE_MD / SYNAPSE_QA_CLAUDE_MD	Override per-bot CLAUDE.md paths shown in the dashboard.
PROJECT_ROOT	Override the directory treated as your project root.

users.json — team identity

Copy users.example.json to users.json (gitignored — never commit). Defines:

• Synapse identity slugs for your team members + bots
• Each member's Discord ID, display name, avatar URL, chat-square emoji
• Which member is the "primary" (used for whitelisted-webhook attribution)
• Optional list of additional Discord bot IDs to filter from the inbound relay

Synapse loads users.json at startup and falls back to users.example.json if missing (with a console warning).

---

✨ Features

🛡️ Concurrency safety

• Distributed file locks with 30-minute auto-expiry — no hard cleanup needed if a bot crashes
• Pre-edit hook consults the central server before every Write/Edit, blocks if locked
• Recent-edit warnings — non-blocking heads-up when another bot touched a file in the last 10 min
• Shared-files watchlist — extra-strict checks for hot files (e.g. package.json, root configs)

📡 Real-time coordination

• WebSocket message bus — <100ms push latency between bots
• Channel push — server-originated messages appear inside a running Claude conversation as <channel> tags
• Activity feed — every edit / commit / lock / build / QA result logged and streamed
• Alerts — priority push notifications between bots ("hey, the auth tests broke on your branch")

🪝 Claude Code hooks

• pre-edit-check.js — blocks edits to locked files; warns on shared-file edits
• post-sync.js — logs every edit + Bash command back to Synapse for the activity feed
• auto-checkpoint.js — commits WIP every 5 edits per agent (distributed-systems thinking applied to LLM agents)
• Session check-in / check-out / user-prompt hooks for full lifecycle visibility

🖥️ Dashboard

• Discord-style web UI at http://localhost:4100 — single HTML file, no build step
• Live activity stream with per-bot avatars, role colors, channel tags
• File-lock visualisation — see what's locked, by whom, and when it auto-expires
• Build & QA panels — track results across bots without leaving the dashboard
• GitHub activity widget — recent commits + PR status

🔌 Discord integration (optional)

• Outbound mirror — relay Synapse messages to Discord via webhook
• Inbound relay — pipe Discord channel messages back into Synapse so humans can chat with bots from their phone
• Echo-loop prevention — known-bot allowlist + webhook whitelist prevents feedback loops

---

🧪 The use case it was built for

I run 2-4 Claude Code instances simultaneously on the same large codebase. Each lives on a different branch:

• Backend Bot on back-end — APIs, database, agents
• Frontend Bot on front-end — React, Tailwind, UI components
• QA Bot on main — tests, code review, Playwright automation
• Sometimes a fourth — docs, ops, infra

Without coordination, they ship conflicting changes, race on shared files, and waste tokens re-discovering each other's work. With Synapse, the QA Bot pushes a critical-issue message into the Backend Bot's running conversation the moment a test breaks, the Frontend Bot can tell the Backend Bot it's about to migrate a route, and package.json only ever gets edited by one of them at a time.

If you're running multi-bot Claude Code dev workflows, Synapse is what you wish you had after the second time two bots clobbered each other's package.json.

---

🛣️ Roadmap

• Web-only fallback for users without Discord
• Per-channel rate-limiting + queueing
• Persistent activity log retention beyond in-memory + JSON
• Test suite for the Channel pattern's reconnection edge cases
• Public Postgres backend (currently file-state, fine up to ~10 bots)
• Native MCP tools/list & tools/call schema validation in Channel server

---

🤝 Contributing

Synapse is in active personal use. PRs welcome — particularly around:

• New hook scripts for additional Claude Code lifecycle events
• Adapters for other agent frameworks (Cursor, Aider, etc.)
• Dashboard improvements (search, filters, theming)
• Docs / examples / tutorials

Open an issue first if you want to discuss a larger change.

---

📄 License

MIT — use it, fork it, ship it. Attribution appreciated but not required.

---

🙋 Author

Built by Ben Cole (@ZSlayerHQ) — AI engineer working on multi-agent systems and Model Context Protocol servers.

If Synapse is useful to you, a ⭐ on this repo is the easiest way to say thanks.

---

Made with too many parallel Claude Code conversations.