claude-peers-mcp
Enable multiple Claude Code instances to discover each other and exchange messages in real-time via a local broker daemon and MCP server.
- Installs
- 1K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/reason-machines/trending-skills --skill claude-peers-mcp- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads claude-peers-mcp automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
claude-peers-mcp
Skill by ara.so — Daily 2026 Skills collection.
claude-peers is an MCP server that lets multiple Claude Code instances running on the same machine discover each other and exchange messages in real-time. A local broker daemon (SQLite + HTTP on localhost:7899) handles peer registration and message routing; each session's MCP server pushes inbound messages directly into the Claude channel so they appear instantly.
Installation
1. Clone and install dependencies
git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp
cd ~/claude-peers-mcp
bun install
2. Register as a global MCP server
claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts
Adjust the path if you cloned elsewhere.
3. Launch Claude Code with the channel enabled
claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers
Add a shell alias to avoid typing it every time:
# ~/.bashrc or ~/.zshrc
alias claudepeers='claude --dangerously-load-development-channels server:claude-peers'
The broker daemon starts automatically on first use. No manual daemon management needed.
Requirements
- Bun runtime
- Claude Code v2.1.80+
- claude.ai login (channels require it — API key auth does not work)
Architecture
┌───────────────────────────┐
│ broker daemon │
│ localhost:7899 + SQLite │
└──────┬───────────────┬────┘
│ │
MCP server A MCP server B
(stdio) (stdio)
│ │
Claude A Claude B
- Each Claude Code session spawns its own
server.tsMCP process over stdio - MCP servers register with the broker and poll every second
- Inbound messages are pushed via the
claude/channelprotocol for instant delivery - The broker auto-cleans dead peers and is localhost-only
MCP Tools Reference
| Tool | Description |
|---|---|
list_peers | Discover other Claude Code instances; scope: machine, directory, or repo |
send_message | Send a message to a peer by ID — delivered instantly via channel push |
set_summary | Set a description of what this instance is working on |
check_messages | Manually poll for messages (fallback without channel mode) |
Example prompts to Claude
List all peers on this machine
Send a message to peer abc123: "what files are you editing right now?"
Set your summary to: "refactoring the authentication module"
Check for any new messages from peers
CLI Usage
Inspect and interact with the broker directly from the terminal:
cd ~/claude-peers-mcp
# Show broker status and all registered peers
bun cli.ts status
# List peers in a table
bun cli.ts peers
# Send a message into a specific Claude session
bun cli.ts send <peer-id> "your message here"
# Stop the broker daemon
bun cli.ts kill-broker
Configuration
Set these environment variables before starting Claude Code:
| Variable | Default | Description |
|---|---|---|
CLAUDE_PEERS_PORT | 7899 | Port the broker listens on |
CLAUDE_PEERS_DB | ~/.claude-peers.db | Path to the SQLite database |
OPENAI_API_KEY | — | Enables auto-summary via gpt-4o-mini on startup |
export CLAUDE_PEERS_PORT=7899
export CLAUDE_PEERS_DB=~/.claude-peers.db
export OPENAI_API_KEY=$OPENAI_API_KEY # optional — enables auto-summary
Auto-Summary Feature
With OPENAI_API_KEY set, each instance generates a brief summary on startup describing what you're likely working on (based on working directory, git branch, recent files). Other peers see this in list_peers output. Without the key, Claude sets its own summary via set_summary.
Common Patterns
Cross-project coordination
Start two sessions in different project directories:
# Terminal 1 — in ~/projects/backend
claudepeers
# Terminal 2 — in ~/projects/frontend
claudepeers
Ask Claude in Terminal 1:
List peers scoped to machine, then ask the peer in the frontend project what API endpoints it needs
Scope-filtered peer discovery
List peers scoped to repo
Shows only instances running in the same git repository — useful when you have worktrees or split terminals on the same codebase.
Scripted message injection via CLI
# Inject a task into a running Claude session from a shell script
PEER_ID=$(bun ~/claude-peers-mcp/cli.ts peers | grep 'backend' | awk '{print $1}')
bun ~/claude-peers-mcp/cli.ts send "$PEER_ID" "run the test suite and report failures"
Polling fallback (no channel mode)
If you launch without --dangerously-load-development-channels, Claude can still receive messages by calling check_messages explicitly:
Check for any new peer messages
Troubleshooting
Broker not starting
# Check if something is already on port 7899
lsof -i :7899
# Kill a stuck broker and restart
bun ~/claude-peers-mcp/cli.ts kill-broker
# Then relaunch Claude Code
Peers not appearing in list_peers
- Ensure both sessions were started with
--dangerously-load-development-channels server:claude-peers - Confirm both use the same
CLAUDE_PEERS_PORT(default7899) - Run
bun cli.ts statusto verify the broker sees both registrations
Messages not arriving instantly
- Channel push requires claude.ai login; API key auth won't work
- Fall back to
check_messagestool if channels are unavailable
Auto-summary not generating
- Verify
OPENAI_API_KEYis exported in the shell where Claude Code was launched:echo $OPENAI_API_KEY - The feature uses
gpt-4o-mini; confirm your key has access
Database issues
# Reset the database entirely (all peers/messages lost)
rm ~/.claude-peers.db
bun ~/claude-peers-mcp/cli.ts kill-broker
MCP server not found after registration
# Verify registration
claude mcp list
# Re-register if missing
claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts
FAQ
What does the claude-peers-mcp skill do?
Enable multiple Claude Code instances to discover each other and exchange messages in real-time via a local broker daemon and MCP server.
How do I install claude-peers-mcp?
Run npx skills add https://github.com/reason-machines/trending-skills --skill claude-peers-mcp in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/claude-peers-mcp/ (personal) or .claude/skills/claude-peers-mcp/ (project).
Which AI agents can use claude-peers-mcp?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is claude-peers-mcp safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains claude-peers-mcp?
It is published by reason-machines in reason-machines/trending-skills. It has 1,046 recorded installs.
More from reason-machines/trending-skills
openclaw-control-center
reason-machines/trending-skills
Local-first, security-first control center for OpenClaw agents — visibility dashboard with readonly defaults, token attribution, collaboration tracing, and safe write operations.
inkos-multi-agent-novel-writing
reason-machines/trending-skills
Multi-agent CLI system for autonomous novel writing, auditing, and revision with human review gates
claude-hud-statusline
reason-machines/trending-skills
A Claude Code plugin that displays a real-time HUD showing context usage, active tools, running agents, and todo progress in your terminal statusline.
understand-anything-knowledge-graph
reason-machines/trending-skills
Turn any codebase into an interactive knowledge graph using Claude Code skills — explore, search, and ask questions about any project visually.
agency-agents-ai-specialists
reason-machines/trending-skills
A collection of specialized AI agent personalities for Claude Code, Cursor, Aider, Windsurf, and other AI coding tools — covering engineering, design, marketing, sales, and more.
agent-browser-automation
reason-machines/trending-skills
Headless browser automation CLI for AI agents using native Rust binary with Chrome DevTools Protocol
Popular ai & agents skills
google-agents-cli-publish
google/agents-cli
This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).
google-agents-cli-eval
google/agents-cli
This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).
skill-creator
anthropics/skills
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
codex-pet
prime-skills/runcomfy-agent-skills
Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.
full-output-enforcement
leonxlnx/taste-skill
Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.
executing-plans
obra/superpowers
Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available