claude-peers-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

由ara.so开发的Skill — 2026每日技能合集。

claude-peers是一个MCP服务器，可让同一台机器上运行的多个Claude Code实例互相发现并实时交换消息。本地代理守护进程（SQLite + HTTP，运行在

localhost:7899

）处理节点注册和消息路由；每个会话的MCP服务器会将入站消息直接推送到Claude频道，使其即时显示。

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 as a global MCP server

2. 注册为全局MCP服务器

bash

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

Adjust the path if you cloned elsewhere.

bash

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

如果克隆到了其他路径，请调整上述路径。

3. Launch Claude Code with the channel enabled

3. 启用频道功能启动Claude Code

bash

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

Add a shell alias to avoid typing it every time:

bash

undefined

bash

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

可以添加Shell别名，避免每次重复输入：

bash

undefined

~/.bashrc or ~/.zshrc

~/.bashrc 或 ~/.zshrc

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


The broker daemon starts automatically on first use. No manual daemon management needed.

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


代理守护进程会在首次使用时自动启动，无需手动管理。

Requirements

环境要求

Bun runtime
Claude Code v2.1.80+
claude.ai login (channels require it — API key auth does not work)

Bun 运行时
Claude Code v2.1.80+
claude.ai登录（频道功能需要该登录方式，API密钥认证无法使用）

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.ts
```
MCP process over stdio
MCP servers register with the broker and poll every second
Inbound messages are pushed via the
```
claude/channel
```
protocol for instant delivery
The broker auto-cleans dead peers and is localhost-only

                    ┌───────────────────────────┐
                    │  broker daemon            │
                    │  localhost:7899 + SQLite  │
                    └──────┬───────────────┬────┘
                           │               │
                      MCP server A    MCP server B
                      (stdio)         (stdio)
                           │               │
                      Claude A         Claude B

每个Claude Code会话都会通过stdio启动自己的
```
server.ts
```
MCP进程
MCP服务器会向代理注册，并每秒轮询一次
入站消息通过
```
claude/channel
```
协议推送，实现即时送达
代理会自动清理失效节点，且仅在本地主机运行

MCP Tools Reference

MCP工具参考

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)

工具	描述
`list_peers`	发现其他Claude Code实例；范围可选： `machine` （机器）、 `directory` （目录）或 `repo` （仓库）
`send_message`	通过ID向指定节点发送消息 — 频道推送实现即时送达
`set_summary`	设置当前实例的工作描述
`check_messages`	手动轮询消息（无频道模式时的备选方案）

Example prompts to Claude

向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

列出这台机器上的所有节点

向节点abc123发送消息："你现在正在编辑哪些文件？"

将你的工作描述设置为："重构认证模块"

检查是否有来自其他节点的新消息

CLI Usage

CLI使用方法

Inspect and interact with the broker directly from the terminal:

bash

cd ~/claude-peers-mcp

直接从终端检查并与代理交互：

bash

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

向特定Claude会话发送消息

bun cli.ts send <peer-id> "your message here"

bun cli.ts send <peer-id> "你的消息内容"

Stop the broker daemon

停止代理守护进程

bun cli.ts kill-broker

undefined

bun cli.ts kill-broker

undefined

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

bash

export CLAUDE_PEERS_PORT=7899
export CLAUDE_PEERS_DB=~/.claude-peers.db
export OPENAI_API_KEY=$OPENAI_API_KEY  # optional — enables auto-summary

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

变量	默认值	描述
`CLAUDE_PEERS_PORT`	`7899`	代理监听的端口
`CLAUDE_PEERS_DB`	`~/.claude-peers.db`	SQLite数据库的路径
`OPENAI_API_KEY`	—	启用启动时通过 `gpt-4o-mini` 自动生成摘要的功能

bash

export CLAUDE_PEERS_PORT=7899
export CLAUDE_PEERS_DB=~/.claude-peers.db
export OPENAI_API_KEY=$OPENAI_API_KEY  # 可选 — 启用自动摘要功能

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

设置

OPENAI_API_KEY

后，每个实例在启动时会生成一个简短摘要，描述你当前可能正在进行的工作（基于工作目录、Git分支、最近操作的文件）。其他节点可在

list_peers

的输出中看到该摘要。如果未设置密钥，可通过

set_summary

让Claude自行设置摘要。

Common Patterns

常见使用场景

Cross-project coordination

跨项目协作

Start two sessions in different project directories:

bash

undefined

在不同项目目录中启动两个会话：

bash

undefined

Terminal 1 — in ~/projects/backend

终端1 — 位于~/projects/backend

claudepeers

Terminal 2 — in ~/projects/frontend

终端2 — 位于~/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

undefined

claudepeers


在终端1中询问Claude：

列出机器范围内的所有节点，然后询问前端项目中的节点需要哪些API接口

undefined

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.

列出仓库范围内的节点

仅显示在同一Git仓库中运行的实例 — 当你在同一代码库中使用工作树或拆分终端时非常有用。

Scripted message injection via CLI

通过CLI脚本注入消息

bash

undefined

bash

undefined

Inject a task into a running Claude session from a shell script

从Shell脚本向运行中的Claude会话注入任务

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"

undefined

PEER_ID=$(bun ~/claude-peers-mcp/cli.ts peers | grep 'backend' | awk '{print $1}') bun ~/claude-peers-mcp/cli.ts send "$PEER_ID" "运行测试套件并报告失败情况"

undefined

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

如果启动时未添加

--dangerously-load-development-channels

参数，Claude仍可通过显式调用

check_messages

来接收消息：

检查是否有新的节点消息

Troubleshooting

故障排除

Broker not starting

bash

undefined

代理无法启动

bash

undefined

Check if something is already on port 7899

检查端口7899是否被占用

lsof -i :7899

Kill a stuck broker and restart

终止卡住的代理并重启

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

Then relaunch Claude Code

然后重新启动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` (default `7899`)
- Run `bun cli.ts status` to 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_messages` tool if channels are unavailable

**Auto-summary not generating**
- Verify `OPENAI_API_KEY` is 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**
```bash


**`list_peers`中看不到节点**
- 确保两个会话都使用`--dangerously-load-development-channels server:claude-peers`启动
- 确认两者使用相同的`CLAUDE_PEERS_PORT`（默认7899）
- 运行`bun cli.ts status`验证代理是否已注册两个实例

**消息无法即时送达**
- 频道推送需要claude.ai登录；API密钥认证无效
- 如果频道不可用，可使用`check_messages`工具作为备选

**自动摘要无法生成**
- 验证启动Claude Code的Shell中是否已导出`OPENAI_API_KEY`：`echo $OPENAI_API_KEY`
- 该功能使用`gpt-4o-mini`；请确认你的密钥有权限访问该模型

**数据库问题**
```bash

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**
```bash

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


**注册后找不到MCP服务器**
```bash

Verify registration

验证注册状态

claude mcp list

Re-register if missing

如果丢失则重新注册

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

undefined

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

undefined