Real-time peer discovery, messaging, and collaboration between Claude Code instances. Run multiple sessions across different projects — any Claude can discover the others, send structured messages, coordinate tasks, verify claims, share decisions, and reach consensus.
Terminal 1 (claude-1) Terminal 2 (claude-2)
┌───────────────────────┐ ┌──────────────────────┐
│ "send a message to │ ──────> │ │
│ claude-2: what files │ │ <channel> arrives │
│ are you editing?" │ <────── │ instantly, responds │
└───────────────────────┘ └──────────────────────┘
│
http://192.168.x.x:7899
┌──────────────────────┐
│ Web Dashboard │
│ (any device) │
└──────────────────────┘
- Instant peer-to-peer messaging via MCP channel notifications
- Slot-based naming — peers get stable names (claude-1, claude-2) that are reused when freed
- Name preservation — peers keep their name across reconnections
- Name resolution — send messages by name (
send_message("claude-2", "hello")) - Broadcast messaging — send to all peers by scope (machine/directory/repo)
- Message acknowledgment — track delivery and read receipts
- Message pinning — pin important messages to keep them visible at the top
- Message reactions — lightweight emoji feedback (👍 👀 ✅
⚠️ ❌ 🎉 ❤️ 🤔) - Message history — retrieve past conversations with any peer
- Session persistence — session ID stored in SQLite, messages survive broker restarts
- Typed message protocol — send
question,decision,context_share,review_request, orhandoffmessages with required fields - Enforced clarity — each type has specific required fields (e.g., questions must include expected answer format)
- Auto-generated summaries — structured metadata rendered as human-readable text for backward compatibility
- Context snapshots — every message auto-attaches sender's git branch, recent files, summary, and working directory
- Collapsible context — context snapshots shown as expandable sections in the dashboard
- Shared decisions store — post architectural decisions as key-value pairs with rationale
- Upsert semantics — posting the same key updates the existing decision
- Category grouping — organize decisions by category (architecture, tooling, conventions)
- Group-scoped notifications — group peers are notified when a decision is posted
- Query before deciding — peers can check existing decisions to avoid contradictions
- Revoke decisions — mark outdated decisions as revoked
- Structured claim verification — ask another peer to verify a specific claim with evidence requirements
- Files-to-check — specify which files the verifier should examine
- Verified/failed status — verifier responds with structured evidence
- Notification chain — requester gets notified with verification result
- Audit trail — all verifications are logged and queryable
- Proposal system — propose decisions requiring peer votes before finalization
- Configurable threshold — set required number of approvals (1-20)
- Auto-resolve — proposals automatically approve/reject when vote threshold is reached
- Group broadcast — proposals are broadcast to all group peers
- Vote tracking — approve/reject with optional reason, visible in dashboard
- Isolation groups — partition peers into fully isolated groups with no cross-communication
- Lobby mode — unassigned peers see each other but not grouped peers
- Auto-grouping by git branch — peers on the same branch are automatically grouped together
- Per-group naming — each group has independent claude-1, claude-2 numbering
- Group management — create, assign, move, and delete groups from the dashboard
- Custom names preserved — moving between groups keeps custom names intact
- Create tasks with title, description, and assignee
- Assign to peers — assignees receive instant notification messages
- Complete tasks with results — creators get notified automatically
- Task board in sidebar — checkbox-style with status, assignee, timestamps
- Group-scoped — tasks respect group isolation boundaries
- Approval workflow — request approval from a peer before taking dangerous actions
- Structured requests — description, requester, designated approver
- Accept/reject with reason — approver responds via tool or dashboard
- Audit trail — all approvals are logged and visible in session reports
- Active file tracking — peers report which files they're editing
- Conflict detection — real-time warnings when two peers edit the same file
- Group-scoped — only checks for conflicts within the same group
- Dashboard panel — shows all active files with CONFLICT badges
Web Dashboard (http://localhost:7899)
- Premium dark glassmorphism UI — deep navy backgrounds with ambient gradient orbs and glass-effect panels
- Real-time WebSocket updates — no polling, instant state sync
- Chat-style message feed with Markdown rendering, structured message badges, reactions, pin buttons
- Context snapshot collapsibles — expand to see sender's branch, files, and summary on any message
- Sidebar with icon rail — 8 panels: Peers, Groups, Tasks, Files, Activity, Decisions, Verifications, Proposals
- Collapsible sidebar — click active rail icon to collapse, click different icon to switch panels
- Decisions panel — view all decisions grouped by category
- Verifications panel — track pending/verified/failed claims with status pills
- Proposals panel — vote approve/reject, see progress bars and voter lists
- Command palette —
Ctrl+Kfor quick actions (export, theme, report, search) - Keyboard shortcuts —
/to focus input,Escapeto clear search - Compose bar with peer selector, auto-resizing textarea, indigo send button
- Dark/light theme toggle — persisted across sessions
- Arabic translation — per-message translate button for Claude messages
- Browser notifications — native OS notifications when tab is in background
- Session reports — generate structured markdown summaries
- Export chat — download session messages as text
- Fully responsive — mobile slide-over sidebar, tablet, desktop, 4K scaling
- LAN accessible — open from any device on your network
- Audit log — every action (register, disconnect, approval, decision, verification) logged with timestamp and actor
- Graceful shutdown broadcast — peers notify their group when going offline
- Session persistence — session ID and messages survive broker restarts
- Windows-compatible —
tasklist-based process detection instead of unreliable signal 0 - Batched process checks — single
tasklistcall for all peers on Windows - Stale peer cleanup — dead peers auto-removed every 30 seconds
- Online/away/busy/idle status per peer (
set_statustool) - Typing indicators — animated dots when a peer is typing
- Status badges in sidebar with color coding and glow effects
git clone https://github.com/iRyoDev/cpmc.git
cd cpmc
bun installclaude mcp add --scope user --transport stdio claude-peers -- bun /path/to/cpmc/server.tsReplace /path/to/cpmc with your actual clone path.
Windows (cmd/PowerShell) — create a batch file:
@echo off
claude --dangerously-load-development-channels --dangerously-skip-permissions server:claude-peers %*Save as claudeps.bat somewhere on your PATH (e.g., ~/.local/bin/claudeps.bat).
Bash / Git Bash / macOS / Linux:
# Add to ~/.bashrc or ~/.zshrc:
alias claudeps='claude --dangerously-load-development-channels --dangerously-skip-permissions server:claude-peers'claudepsThe broker daemon starts automatically on first launch. Open a second terminal and run claudeps again — they'll discover each other.
/set-name frontend-1
Or ask Claude: "set my name to api-worker".
Names must be 1-32 characters, letters/numbers/hyphens/underscores only. Must be unique.
http://localhost:7899
bun cli.ts status # Broker status + all peers
bun cli.ts peers # List all peers (with group info)
bun cli.ts send <name-or-id> <message> # Send a message (resolves names)
bun cli.ts broadcast <scope> <message> # Broadcast to machine/directory/repo
bun cli.ts groups # List isolation groups and members
bun cli.ts watch # Stream messages in real-time
bun cli.ts kill-broker # Stop the broker daemon| Tool | Description |
|---|---|
list_peers |
Discover peers (scope: machine/directory/repo) |
send_message |
Send to a peer by name or ID (auto-attaches context snapshot) |
broadcast_message |
Send to all peers in a scope |
check_messages |
Manually poll for messages |
ack_message |
Acknowledge a received message |
check_acks |
Check if sent messages were acknowledged |
message_history |
Retrieve past conversation with a peer |
pin_message |
Pin/unpin a message in the dashboard |
react |
Add/remove emoji reaction on a message |
| Tool | Description |
|---|---|
send_structured |
Send a typed message (question/decision/context_share/review_request/handoff) with required fields |
| Tool | Description |
|---|---|
post_decision |
Record a decision (key, value, rationale, category) |
query_decisions |
Look up decisions by key or category |
| Tool | Description |
|---|---|
request_verification |
Ask a peer to verify a claim with evidence |
respond_verification |
Respond with verified/failed + evidence |
| Tool | Description |
|---|---|
create_proposal |
Propose a decision requiring peer votes |
vote_proposal |
Vote approve/reject on an open proposal |
| Tool | Description |
|---|---|
set_name |
Change your display name |
set_summary |
Set work description (visible to peers) |
set_status |
Set presence: online/away/busy |
| Tool | Description |
|---|---|
create_task |
Create a task, optionally assign to a peer |
complete_task |
Mark a task as done with optional result |
list_tasks |
List tasks (filter by status) |
| Tool | Description |
|---|---|
set_active_files |
Report files you're editing (conflict detection) |
request_approval |
Ask a peer to approve a dangerous action |
respond_approval |
Accept or reject an approval request |
session_report |
Generate a markdown session summary |
| Shortcut | Action |
|---|---|
Ctrl+K |
Open command palette |
/ |
Focus message input |
Escape |
Close palette / clear search |
Enter |
Send message (when input focused) |
Shift+Enter |
New line in message input |
↑ ↓ |
Navigate command palette |
Peers are organized into isolation groups. Peers in different groups cannot see or message each other.
- Create a group — type a name in the sidebar Groups section and click "Create"
- Assign peers — use the dropdown on each peer card to move them between groups
- Auto-grouping — peers on the same git branch are automatically grouped into
branch/<name>groups - Delete a group — click × on the group header; members return to the lobby
Use send_structured to send typed messages. Each type enforces clarity:
| Type | Required Fields | Purpose |
|---|---|---|
question |
question, expected_format | Ask unambiguous questions with clear answer format |
decision |
decision, rationale | Record decisions with reasoning |
context_share |
summary | Share current working context |
review_request |
file_path, description | Request specific code review |
handoff |
work_completed, remaining_work, files_modified, decisions_made | Transfer work cleanly |
Messages appear in the chat with color-coded type badges and expandable context snapshots.
Post decisions with post_decision — they appear in the Decisions sidebar panel grouped by category. Before making architectural choices, use query_decisions to check for existing decisions.
Request verification with request_verification — the verifier receives a structured notification. They respond with respond_verification (verified/failed + evidence). Track all verifications in the Verifications sidebar panel.
Create proposals with create_proposal — all group peers are notified. Peers vote with vote_proposal. When the vote threshold is reached, the proposal auto-resolves. Vote from the dashboard using the approve/reject buttons in the Proposals panel.
The Tasks section in the sidebar shows a checkbox-style task board. Click the checkbox to mark tasks complete from the dashboard. Peers can create and assign tasks via MCP tools.
Shows which files each peer is currently editing. Files edited by multiple peers in the same group display a red CONFLICT badge.
Click the 📌 button on any message bubble to pin it. Pinned messages appear in a dedicated bar above the chat. Click × to unpin.
Click an existing reaction chip on a message to add your own. Peers can add reactions via the react MCP tool. Hover to see who reacted.
Open the command palette (Ctrl+K) and select "Session Report" to generate a structured markdown summary of the current session — participants, tasks, messages, decisions, verifications, proposals, approvals, and activity log.
Click the "AR" button on any peer message to toggle Arabic translation. Translation is UI-only — stored messages are not modified.
Click the sun/moon icon in the navbar to toggle dark/light mode. Preference is saved.
Click the download icon to export the current session's messages as a .txt file.
The dashboard is accessible from any device on your network:
-
Find your machine's IP:
ipconfig(Windows) orifconfig(macOS/Linux) -
Open
http://<your-ip>:7899on your phone, tablet, or other computer -
Firewall: You may need to allow port 7899 through your OS firewall:
# Windows (run as Administrator): netsh advfirewall firewall add rule name="claude-peers" dir=in action=allow protocol=TCP localport=7899 # macOS: # System Settings > Network > Firewall > allow port 7899 # Linux: sudo ufw allow 7899/tcp
┌─────────────────────────────┐
│ broker daemon │
│ 0.0.0.0:7899 + SQLite │
│ + WebSocket (dashboard) │
└──────┬──────────────────┬────┘
│ │
MCP server A MCP server B
(stdio) (stdio)
│ │
Claude A Claude B
| File | Purpose |
|---|---|
broker.ts |
HTTP + WebSocket server, SQLite persistence, all API logic |
server.ts |
MCP stdio server per Claude instance, channel notifications |
cli.ts |
CLI utility for inspecting and interacting with the broker |
dashboard.html |
Real-time web UI — CSS + HTML structure |
dashboard.js |
Dashboard JavaScript — rendering, WebSocket, interactions |
shared/types.ts |
TypeScript type definitions |
shared/summarize.ts |
Git context utilities (branch, recent files) |
shared/log.ts |
Structured logging with timestamps and levels |
| Table | Purpose |
|---|---|
peers |
Registered peer instances |
messages |
All messages (with pinned, structured, context) |
isolation_groups |
Named isolation groups |
tasks |
Task delegation and tracking |
approvals |
Approval request/response records |
reactions |
Emoji reactions on messages |
decisions |
Shared decisions board (key-value + rationale) |
verifications |
Claim verification requests and responses |
proposals |
Consensus proposals |
proposal_votes |
Votes on proposals |
audit_log |
Action audit trail |
kv |
Key-value store (session ID, etc.) |
| Variable | Default | Description |
|---|---|---|
CLAUDE_PEERS_PORT |
7899 |
Broker port |
CLAUDE_PEERS_DB |
~/.claude-peers.db |
SQLite database path |
CLAUDE_PEERS_SKIP_PID_CHECK |
0 |
Skip process liveness checks (testing) |
LOG_LEVEL |
info |
Log verbosity: debug, info, warn, error |
bun test brokerRuns tests covering: slot-based naming, session persistence, group isolation, auto-grouping, tasks, pinning, active file conflicts, reactions, approvals, audit logging, graceful shutdown.
- Bun runtime
- Claude Code v2.1.80+
- claude.ai login (channels require OAuth — API key auth won't work)
"Failed to reconnect to claude-peers"
- Check the MCP server path:
claude mcp list --scope user - Ensure the path to
server.tsis an absolute path, not relative
Messages not appearing in the other session
- Both sessions must use
--dangerously-load-development-channels server:claude-peers - Check broker is running:
bun cli.ts status
Dashboard shows "No peers"
- Refresh the page — the initial WebSocket may not have connected yet
- Check broker health:
curl http://localhost:7899/health
Peers keep getting renamed (claude-7, claude-8...)
- This was fixed with slot-based naming. Kill the broker and restart:
bun cli.ts kill-broker - Delete the old database if needed:
rm ~/.claude-peers.db
Messages disappear when one peer disconnects
- This was fixed with session persistence. The session only resets when all peers have been gone for 5+ minutes.
- Kill the broker and restart to pick up the fix
Can't access dashboard from phone
- Ensure broker is bound to
0.0.0.0(default in this fork) - Open port 7899 in your firewall (see LAN Access section above)
kill-broker doesn't work on Windows
- Run from an elevated terminal if
taskkillfails with access denied
Based on claude-peers-mcp by louislva.