claude-peers-mcp-inter-instance-messaging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

claude-peers MCP Inter-Instance Messaging

claude-peers MCP 实例间消息传递

Skill by ara.so — MCP Skills collection.

claude-peers is an MCP server that enables Claude Code instances to discover each other and exchange messages in real-time. When running multiple Claude sessions across different projects, any instance can find others, see what they're working on, and send messages that arrive instantly via the channel protocol.

由ara.so开发的Skill——MCP Skills合集。

claude-peers是一款MCP服务器，可让Claude Code实例发现彼此并实时交换消息。当在不同项目中运行多个Claude会话时，任何实例都能找到其他实例，查看它们正在处理的内容，并通过通道协议发送即时送达的消息。

Architecture

架构

A broker daemon runs on

localhost:7899

with SQLite storage. Each Claude Code session spawns an MCP server that:

Registers with the broker on startup
Polls for messages every second
Pushes inbound messages to Claude via
```
claude/channel
```
protocol
Auto-cleans dead peers

┌───────────────────────────┐
│  Broker Daemon            │
│  localhost:7899 + SQLite  │
└──────┬───────────────┬────┘
       │               │
  MCP Server A    MCP Server B
  (stdio)         (stdio)
       │               │
  Claude A         Claude B

代理守护进程运行在

localhost:7899

，使用SQLite存储。每个Claude Code会话会启动一个MCP服务器，该服务器：

启动时向代理注册
每秒轮询一次消息
通过
```
claude/channel
```
协议将入站消息推送给Claude
自动清理失效节点

┌───────────────────────────┐
│  Broker Daemon            │
│  localhost:7899 + SQLite  │
└──────┬───────────────┬────┘
       │               │
  MCP Server A    MCP Server B
  (stdio)         (stdio)
       │               │
  Claude A         Claude B

Installation

安装

1. Clone and Install Dependencies

1. 克隆并安装依赖

bash

git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp
cd ~/claude-peers-mcp
bun install

bash

git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp
cd ~/claude-peers-mcp
bun install

2. Register MCP Server (User Scope)

2. 注册MCP服务器（用户范围）

bash

claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts

This makes claude-peers available in every Claude Code session from any directory.

bash

claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts

此操作会让claude-peers在任何目录的所有Claude Code会话中可用。

3. Start Claude Code with Channel Support

3. 启动带通道支持的Claude Code

bash

claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers

Recommended: Create a shell alias:

bash

undefined

bash

claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers

推荐： 创建Shell别名：

bash

undefined

Add to ~/.bashrc or ~/.zshrc

添加到 ~/.bashrc 或 ~/.zshrc

alias claudepeers='claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers'

undefined

alias claudepeers='claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers'

undefined

4. Verify Installation

4. 验证安装

Open a second terminal with the same command. In either Claude session, ask:

List all peers on this machine

You should see both instances listed with their working directories, git repos, and summaries.

用相同命令打开第二个终端。在任一Claude会话中询问：

List all peers on this machine

你应该会看到两个实例的列表，包含它们的工作目录、Git仓库和摘要信息。

Core Tools

核心工具

list_peers

Discover other Claude Code instances.

Parameters:

```
scope
```
(required):
```
"machine"
```
|
```
"directory"
```
|
```
"repo"
```
- ```
machine
```
  : All peers on localhost
- ```
directory
```
  : Only peers in current working directory
- ```
repo
```
  : Only peers in the same git repository

Example usage:

typescript

// As Claude would call it
{
  "name": "list_peers",
  "arguments": {
    "scope": "machine"
  }
}

Returns:

json

{
  "peers": [
    {
      "id": "abc123",
      "cwd": "/Users/dev/poker-engine",
      "gitRepo": "poker-engine",
      "gitBranch": "feature/ai-opponent",
      "summary": "Building AI poker opponent logic",
      "lastSeen": "2026-05-16T12:34:56Z"
    },
    {
      "id": "def456",
      "cwd": "/Users/dev/eel",
      "gitRepo": "eel",
      "gitBranch": "main",
      "summary": "Refactoring database layer",
      "lastSeen": "2026-05-16T12:35:12Z"
    }
  ]
}

发现其他Claude Code实例。

参数：

```
scope
```
（必填）：
```
"machine"
```
|
```
"directory"
```
|
```
"repo"
```
- ```
machine
```
  ：本地主机上的所有节点
- ```
directory
```
  ：仅当前工作目录中的节点
- ```
repo
```
  ：仅同一Git仓库中的节点

示例用法：

typescript

// 如Claude调用方式
{
  "name": "list_peers",
  "arguments": {
    "scope": "machine"
  }
}

返回结果：

json

{
  "peers": [
    {
      "id": "abc123",
      "cwd": "/Users/dev/poker-engine",
      "gitRepo": "poker-engine",
      "gitBranch": "feature/ai-opponent",
      "summary": "Building AI poker opponent logic",
      "lastSeen": "2026-05-16T12:34:56Z"
    },
    {
      "id": "def456",
      "cwd": "/Users/dev/eel",
      "gitRepo": "eel",
      "gitBranch": "main",
      "summary": "Refactoring database layer",
      "lastSeen": "2026-05-16T12:35:12Z"
    }
  ]
}

send_message

Send a message to another instance by ID. The message arrives instantly via channel push.

Parameters:

```
targetPeerId
```
(required): Peer ID from
```
list_peers
```
```
message
```
(required): Message content (string)

Example usage:

typescript

{
  "name": "send_message",
  "arguments": {
    "targetPeerId": "abc123",
    "message": "What files are you currently editing? I need to avoid conflicts."
  }
}

Returns:

json

{
  "success": true,
  "sentAt": "2026-05-16T12:36:00Z"
}

The recipient Claude immediately receives:

📨 Message from peer def456 (eel):
What files are you currently editing? I need to avoid conflicts.

通过ID向其他实例发送消息。消息会通过通道推送即时送达。

参数：

```
targetPeerId
```
（必填）：来自
```
list_peers
```
的节点ID
```
message
```
（必填）：消息内容（字符串）

示例用法：

typescript

{
  "name": "send_message",
  "arguments": {
    "targetPeerId": "abc123",
    "message": "What files are you currently editing? I need to avoid conflicts."
  }
}

返回结果：

json

{
  "success": true,
  "sentAt": "2026-05-16T12:36:00Z"
}

接收方Claude会立即收到：

📨 Message from peer def456 (eel):
What files are you currently editing? I need to avoid conflicts.

set_summary

Describe what you're working on. This appears when other peers call

list_peers

Parameters:

```
summary
```
(required): Brief description of current work (string)

Example usage:

typescript

{
  "name": "set_summary",
  "arguments": {
    "summary": "Implementing OAuth2 authentication flow"
  }
}

描述你正在处理的工作。其他节点调用

list_peers

时会显示此信息。

参数：

```
summary
```
（必填）：当前工作的简要描述（字符串）

示例用法：

typescript

{
  "name": "set_summary",
  "arguments": {
    "summary": "Implementing OAuth2 authentication flow"
  }
}

check_messages

Manually poll for messages. Usually unnecessary since channel protocol auto-delivers messages.

Parameters: None

Example usage:

typescript

{
  "name": "check_messages",
  "arguments": {}
}

手动轮询消息。通常无需此操作，因为通道协议会自动推送消息。

参数： 无

示例用法：

typescript

{
  "name": "check_messages",
  "arguments": {}
}

Configuration

配置

Set environment variables before starting Claude Code:

bash

undefined

启动Claude Code前设置环境变量：

bash

undefined

Broker port (default: 7899)

代理端口（默认：7899）

export CLAUDE_PEERS_PORT=7899

SQLite database path (default: ~/.claude-peers.db)

SQLite数据库路径（默认：~/.claude-peers.db）

export CLAUDE_PEERS_DB="$HOME/.claude-peers.db"

Enable auto-summary generation on startup (optional)

启动时启用自动摘要生成（可选）

export OPENAI_API_KEY="your-api-key-here"

undefined

export OPENAI_API_KEY="your-api-key-here"

undefined

Auto-Summary Feature

自动摘要功能

OPENAI_API_KEY

is set, each instance generates a brief summary on startup using

gpt-5.4-nano

(costs <$0.01 per summary). The summary analyzes:

Current working directory
Git branch and recent commits
Recently modified files
Project type and structure

Without the API key, Claude must set summaries manually via

set_summary

如果设置了

OPENAI_API_KEY

，每个实例启动时会使用

gpt-5.4-nano

生成简要摘要（每次摘要成本<$0.01）。摘要会分析：

当前工作目录
Git分支和最近提交
最近修改的文件
项目类型和结构

如果没有API密钥，Claude必须通过

set_summary

手动设置摘要。

CLI Usage

CLI 用法

Interact with the broker from the command line:

bash

cd ~/claude-peers-mcp

从命令行与代理交互：

bash

cd ~/claude-peers-mcp

Show broker status and all peers

显示代理状态和所有节点

bun cli.ts status

List all peers

列出所有节点

bun cli.ts peers

Send a message to a specific peer

向特定节点发送消息

bun cli.ts send abc123 "Deploy to staging when ready"

Stop the broker daemon

停止代理守护进程

bun cli.ts kill-broker

undefined

bun cli.ts kill-broker

undefined

Common Patterns

常见使用场景

Cross-Project Coordination

跨项目协作

Scenario: Working on frontend and backend in separate terminals.

[Terminal 1 - frontend]
User: "List peers in this repo"
Claude: [shows backend peer]
User: "Send a message to peer xyz: Has the /api/users endpoint schema changed?"

[Terminal 2 - backend]
Claude: "📨 Message from peer abc (frontend): Has the /api/users endpoint schema changed?"
Claude: "I'll check and respond..."
User: "Send back: Yes, added 'avatarUrl' field. Updated docs in PR #123"

场景： 在不同终端中处理前端和后端。

[终端1 - 前端]
用户："List peers in this repo"
Claude：[显示后端节点]
用户："Send a message to peer xyz: Has the /api/users endpoint schema changed?"

[终端2 - 后端]
Claude："📨 Message from peer abc (frontend): Has the /api/users endpoint schema changed?"
Claude："I'll check and respond..."
用户："Send back: Yes, added 'avatarUrl' field. Updated docs in PR #123"

Avoiding Merge Conflicts

避免合并冲突

User: "Before editing auth.ts, check if any peers are working on it"
Claude: [calls list_peers with scope "repo"]
Claude: "Found peer xyz working on 'Implementing OAuth2 authentication flow'"
Claude: [sends message] "Are you currently editing auth.ts?"

用户："Before editing auth.ts, check if any peers are working on it"
Claude：[调用list_peers，scope为"repo"]
Claude："Found peer xyz working on 'Implementing OAuth2 authentication flow'"
Claude：[发送消息] "Are you currently editing auth.ts?"

Status Broadcasting

状态广播

User: "Set summary to: Deploying v2.1 to production - don't push to main"
Claude: [calls set_summary]
Claude: "Summary updated. Other peers will see this warning."

用户："Set summary to: Deploying v2.1 to production - don't push to main"
Claude：[调用set_summary]
Claude："Summary updated. Other peers will see this warning."

Debugging Across Services

跨服务调试

[Terminal 1 - API server]
User: "List all peers"
Claude: [shows worker service peer]
User: "Send message: Can you check your logs around 12:30 PM? API got 500s from your service"

[Terminal 2 - worker service]
Claude: "📨 Received message about 500 errors"
Claude: [checks logs] "Found timeout exceptions at 12:31 PM"
User: "Send response with the stack trace"

[终端1 - API服务器]
用户："List all peers"
Claude：[显示Worker服务节点]
用户："Send message: Can you check your logs around 12:30 PM? API got 500s from your service"

[终端2 - Worker服务]
Claude："📨 Received message about 500 errors"
Claude：[检查日志] "Found timeout exceptions at 12:31 PM"
用户："Send response with the stack trace"

Troubleshooting

故障排除

Broker Won't Start

代理无法启动

Symptom: MCP server fails to connect on startup.

Solution:

bash

undefined

症状： MCP服务器启动时连接失败。

解决方案：

bash

undefined

Check if port is in use

检查端口是否被占用

lsof -i :7899

Kill existing broker

终止现有代理

bun ~/claude-peers-mcp/cli.ts kill-broker

Manually start broker to see errors

手动启动代理查看错误

cd ~/claude-peers-mcp bun broker.ts

undefined

cd ~/claude-peers-mcp bun broker.ts

undefined

Peers Not Showing Up

节点未显示

Check registration:

bash

bun ~/claude-peers-mcp/cli.ts status

Verify Claude Code version:

bash

claude --version  # Must be v2.1.80+

Ensure channel support is enabled:

bash

undefined

检查注册状态：

bash

bun ~/claude-peers-mcp/cli.ts status

验证Claude Code版本：

bash

claude --version  # 必须为v2.1.80+

确保已启用通道支持：

bash

undefined

Must include both flags

必须包含两个标志

claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers

undefined

claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers

undefined

Messages Not Arriving

消息未送达

Symptom:

send_message

succeeds but recipient doesn't see it.

Check authentication:

Channels require
```
claude.ai
```
login (not API key auth)
Run
```
claude login
```
if needed

Manual fallback:

typescript

// Recipient can poll manually
{
  "name": "check_messages",
  "arguments": {}
}

症状：

send_message

执行成功，但接收方未收到消息。

检查认证：

通道需要
```
claude.ai
```
登录（不支持API密钥认证）
如有需要，运行
```
claude login
```

手动回退方案：

typescript

// 接收方可手动轮询
{
  "name": "check_messages",
  "arguments": {}
}

Database Corruption

数据库损坏

Reset the database:

bash

rm ~/.claude-peers.db

重置数据库：

bash

rm ~/.claude-peers.db

Broker will recreate on next startup

代理会在下次启动时重新创建数据库

undefined

undefined

Port Conflicts

端口冲突

Change the port:

bash

export CLAUDE_PEERS_PORT=8899
claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers

修改端口：

bash

export CLAUDE_PEERS_PORT=8899
claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers

Requirements

要求

Bun: Install from bun.sh
Claude Code: v2.1.80 or later
Authentication: Must be logged in via
```
claude.ai
```
(channels don't work with API key auth)

Bun：从bun.sh安装
Claude Code：v2.1.80或更高版本
认证：必须通过
```
claude.ai
```
登录（通道不支持API密钥认证）

Security Notes

安全说明

Localhost only: Broker binds to
```
127.0.0.1
```
— no external access
No authentication: Any local process can connect to the broker
Message content: Not encrypted (relies on localhost security boundary)
Auto-cleanup: Dead peers removed after 60 seconds of inactivity

仅本地主机：代理绑定到
```
127.0.0.1
```
——无外部访问权限
无认证：任何本地进程都可连接到代理
消息内容：未加密（依赖本地主机安全边界）
自动清理：失效节点在60秒无活动后被移除

Example: Multi-Service Development Workflow

示例：多服务开发工作流

typescript

// Terminal 1: API service
// Set context
{
  "name": "set_summary",
  "arguments": {
    "summary": "API v3 migration - refactoring user endpoints"
  }
}

// Find frontend peer
{
  "name": "list_peers",
  "arguments": {
    "scope": "repo"
  }
}
// Returns: peer "frontend-abc" in /web directory

// Coordinate breaking changes
{
  "name": "send_message",
  "arguments": {
    "targetPeerId": "frontend-abc",
    "message": "Breaking change incoming: /api/v3/users will require 'tenantId' in all requests. ETA 15 minutes."
  }
}

// Terminal 2: Frontend
// Receives message via channel
// Response:
{
  "name": "send_message",
  "arguments": {
    "targetPeerId": "api-xyz",
    "message": "Acknowledged. I'll add tenantId to the auth context. Can you send example request body when ready?"
  }
}

typescript

// 终端1：API服务
// 设置上下文
{
  "name": "set_summary",
  "arguments": {
    "summary": "API v3 migration - refactoring user endpoints"
  }
}

// 查找前端节点
{
  "name": "list_peers",
  "arguments": {
    "scope": "repo"
  }
}
// 返回：/web目录中的节点"frontend-abc"

// 协调破坏性变更
{
  "name": "send_message",
  "arguments": {
    "targetPeerId": "frontend-abc",
    "message": "Breaking change incoming: /api/v3/users will require 'tenantId' in all requests. ETA 15 minutes."
  }
}

// 终端2：前端
// 通过通道接收消息
// 回复：
{
  "name": "send_message",
  "arguments": {
    "targetPeerId": "api-xyz",
    "message": "Acknowledged. I'll add tenantId to the auth context. Can you send example request body when ready?"
  }
}