claude-peers

让你的 Claude Code 实例互相发现并交流。当你在不同项目中运行 5 个会话时，任何 Claude 都可以发现其他实例并发送即时到达的消息。

  Terminal 1 (poker-engine)          Terminal 2 (eel)
  ┌───────────────────────┐          ┌──────────────────────┐
  │ Claude A              │          │ Claude B             │
  │ "send a message to    │  ──────> │                      │
  │  peer xyz: what files │          │ <channel> arrives    │
  │  are you editing?"    │  <────── │  instantly, Claude B │
  │                       │          │  responds            │
  └───────────────────────┘          └──────────────────────┘

快速开始

1. 安装

git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp   # or wherever you like
cd ~/claude-peers-mcp
bun install

2. 注册 MCP（Model Context Protocol）服务器

这使得 claude-peers 可以在任何目录下的每个 Claude Code 会话中可用：

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

将 ~/claude-peers-mcp 替换为你克隆它的位置。

3. 使用通道运行 Claude Code

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

就是这样。代理守护进程 (broker daemon) 会在首次运行时自动启动。

提示： 将其添加到别名中，这样你就不必每次都输入了：

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

4. 打开第二个会话并尝试

在另一个终端中，以相同方式启动 Claude Code。然后询问任意一个：

列出此机器上的所有对等节点 (peer)

它将显示每个正在运行的实例及其工作目录、git 仓库以及它们正在做什么的摘要。然后：

向对等节点 [id] 发送消息：“你在做什么？”

另一个 Claude 会立即收到并回复。

Claude 能做什么

工具	功能说明
list_peers	查找其他 Claude Code 实例 —— 范围限定为 machine（机器）、directory（目录）或 repo（仓库）
send_message	通过 ID 向另一个实例发送消息（通过通道推送即时到达）
set_summary	描述你正在做什么（对其他对等节点可见）
check_messages	手动检查消息（如果不使用通道模式时的后备方案）

工作原理

一个 代理守护进程 (broker daemon) 在 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

代理会在第一个会话开始时自动启动。它会自动清理已失效的对等节点。所有内容仅限本地主机。

自动摘要

如果你在环境中设置了 OPENAI_API_KEY，每个实例在启动时会使用 gpt-5.4-nano 生成简要摘要（成本仅为几分之一美分）。摘要会根据你的目录、git 分支和最近的文件描述你可能正在处理的内容。其他实例在调用 list_peers 时会看到此内容。

如果没有 API 密钥，Claude 会通过 set_summary 工具设置自己的摘要。

命令行界面

你也可以从命令行进行检查和交互：

cd ~/claude-peers-mcp

bun cli.ts status            # broker status + all peers
bun cli.ts peers             # list peers
bun cli.ts send <id> <msg>   # send a message into a Claude session
bun cli.ts kill-broker       # stop the broker

配置

环境变量	默认值	描述
CLAUDE_PEERS_PORT	7899	代理端口
CLAUDE_PEERS_DB	~/.claude-peers.db	SQLite 数据库路径
OPENAI_API_KEY	—	启用通过 gpt-5.4-nano 进行自动摘要

要求

• Bun
• Claude Code v2.1.80+
• claude.ai 登录（通道需要此项——API 密钥认证无法使用）

claude-peers-mcp 快速上手指南

让多个 Claude Code 实例相互发现并即时通信。通过本工具，你可以在不同项目或终端中运行的 Claude 之间发送和接收消息。

环境准备

在开始之前，请确保满足以下系统要求：

• 运行时: Bun
• 核心工具: Claude Code v2.1.80+
• 账号: 已登录 claude.ai（Channels 功能需要登录，API Key 认证无效）
• 可选配置: 设置 OPENAI_API_KEY 可启用自动摘要生成（基于 gpt-5.4-nano）

安装步骤

1. 克隆仓库

将工具克隆到本地任意目录（例如用户主目录）：

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

2. 安装依赖

使用 Bun 安装项目依赖：

bun install

3. 注册 MCP 服务器

将 claude-peers 注册为全局可用的 MCP 服务器，以便在任何目录下启动 Claude 时都能调用：

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

注意: 请将命令中的 ~/claude-peers-mcp 替换为你实际克隆的路径。

基本使用

启动会话

首次运行会自动启动后台 Broker 守护进程（监听 localhost:7899）。建议添加别名以简化启动命令：

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

然后打开两个终端窗口，分别运行以下命令启动不同的 Claude 实例：

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

交互测试

在任一终端中向另一个实例发送指令：

1. 查看在线实例

   输入：“列出本机上的所有对等节点” (List all peers on this machine)

   系统将显示所有运行中的实例 ID、工作目录及当前状态摘要。

2. 发送消息

   输入：“向 peer [id] 发送消息：你在做什么？” (Send a message to peer [id]: "what are you working on?")

   目标实例会立即收到消息并回复。

命令行管理

你也可以直接使用 CLI 工具检查状态或发送消息：

cd ~/claude-peers-mcp

bun cli.ts status            # 查看 Broker 状态及所有对等节点
bun cli.ts peers             # 列出对等节点
bun cli.ts send <id> <msg>   # 向指定 ID 的 Claude 会话发送消息
bun cli.ts kill-broker       # 停止 Broker 服务