内容
# ipclaude
克劳德代码会话之间的对等消息传递，通过 MCP 和 tmux。
在一台机器上运行多个克劳德代码会话 — 一个领导者，一个后端代理，一个前端代理，一个测试人员 — 让它们直接相互消息传递。使用 `ipc_send` 发送的消息被输入到目标会话的输入框并提交，因此它像来自您的提示一样准确到达。无需守护进程，无需套接字，无需轮询：唯一的活动部件是一个 JSON 注册表文件和 `tmux send-keys`。
```
┌─────────────┐ ipc_send("tester", "API contract: POST /sessions …")
│ 领导者 │ ─────────────────────────────────────────────┐
└─────────────┘ ▼
┌─────────────┐ ┌─────────────┐
│ 前端 │ ◀── [IPC MESSAGE from tester — …] ──── │ 测试人员 │
└─────────────┘ └─────────────┘
每个框都是一个正常的克劳德代码会话，位于自己的 tmux 会话中
```
## 内容
| 文件 | 角色 |
|---|---|
| `server.py` | MCP 服务器，暴露四个工具：`ipc_register`、`ipc_list_sessions`、`ipc_send`、`ipc_unregister`。自包含 [uv](https://docs.astral.sh/uv/) 脚本 — 依赖项在运行时解析。 |
| `bin/ipclaude` | 启动器，包装 `claude` 在 tmux 会话中，并（使用 `-n`/`-r`）预注册它用于 IPC 并设置 🤖 样式的选项卡标题。 |
| `install.sh` | 创建启动器的符号链接，注册 MCP 服务器与克劳德代码。 |
运行时状态是一个文件，`~/.claude/ipc/registry.json`（使用 `CLAUDE_IPC_DIR` 重写目录）。它将短代理名称映射到 tmux 会话名称，并在会话死亡时自动垃圾回收。
## 要求
- macOS 或 Linux（任何具有 tmux 和 TTY 的系统）
- [tmux](https://github.com/tmux/tmux)
- [uv](https://docs.astral.sh/uv/)（运行具有内联依赖项的 MCP 服务器）
- Python ≥ 3.11（任何安装；uv 也会根据需要获取一个）
- [克劳德代码](https://claude.com/claude-code) CLI（`claude` 在 PATH 上）
## 安装
### 快速（脚本）
```bash
git clone https://github.com/JoshuaSP/ipclaude
cd ipclaude
./install.sh
```
脚本是幂等的，如果缺少先决条件，则会大声报错。它将 `bin/ipclaude` 符号链接到 `~/.local/bin` 并在 **用户范围内** 注册 MCP 服务器，因此每个项目都可以使用 `ipc` 工具。
### 为模型（克劳德代码或其他代码代理）
如果您是为用户安装此模型的 AI 代理，请准确执行以下步骤并验证每个步骤：
1. **检查先决条件。** 运行 `command -v tmux uv python3 claude`。所有四个都必须解析。如果任何一个缺失，请停止并报告 — 不要替换另一个终端多路复用器或包运行器。
2. **克隆存储库** 到永久位置（从检出运行，而不是复制）：
```bash
git clone https://github.com/JoshuaSP/ipclaude ~/ipclaude
```
3. **安装启动器：**
```bash
mkdir -p ~/.local/bin
ln -sf ~/ipclaude/bin/ipclaude ~/.local/bin/ipclaude
```
验证：`command -v ipclaude` 解析。如果不是，`~/.local/bin` 不在 PATH 中 — 将 `export PATH="$HOME/.local/bin:$PATH"` 添加到用户的 shell 配置文件中，并告诉他们。
4. **注册 MCP 服务器** （用户范围 — 在所有项目中可用）：
```bash
claude mcp add --scope user ipc -- uv run ~/ipclaude/server.py
```
对于单个项目，请在项目根目录下运行相同的命令，并写入 `.mcp.json`（参见 `.mcp.json.example`）。
5. **验证：** `claude mcp list` 显示 `ipc`。然后使用 `ipclaude -n test` 启动会话，并确认 `ipc_list_sessions` 工具在其中有效（它应报告 `test (you)`）。
6. **报告** 给用户：存储库的位置、注册的范围以及启动方式（`ipclaude -n <name>`）。
## 用法
### 启动会话
```bash
ipclaude -n backend # 新的 tmux 会话，命名为 "backend"，预注册用于 IPC
ipclaude -n frontend # 第二个代理
ipclaude -r backend # 恢复：可重新连接的名称，重新注册用于 IPC
ipclaude # 匿名会话（稍后使用 ipc_register 注册）
ipclaude -p "fix the bug" # 传递任何其他 claude 参数
```
`-n`/`-r` 均命名 tmux 会话 **和** 预注册它到 IPC 注册表中，以便会话可以立即发送和接收消息 — 无需克劳德调用 `ipc_register`。在现有的 tmux 会话中运行，`ipclaude` 重用它；在 tmux 外部，它创建一个。
您也可以在任何 tmux 会话中运行普通的 `claude` 并要求它注册自己： *"注册为 IPC 作为 reviewer"*。
### 消息传递
在任何已注册的会话中，只需自然语言询问：
> 还有谁在 IPC 上？
> → 克劳德调用 `ipc_list_sessions`：`backend (you)`，`frontend`，`tester`
> 告诉 frontend 会话端点已准备好，位于 POST /api/sessions，载荷 {name}
> → 克劳德调用 `ipc_send(name="frontend", message=…)
前端会话接收，作为普通输入：
```
[IPC MESSAGE from backend — reply via ipc_send] 会话端点已准备好，位于 POST /api/sessions，载荷 {name}
```
消息是 **fire-and-forget**。没有交付收据，也没有回复通道 — 回复只是另一个反向的 `ipc_send`。发件人标签自动添加。
### 工具参考
| 工具 | 参数 | 行为 |
|---|---|---|
| `ipc_register` | `name`（≤ 48 个字符） | 加入 IPC。声明名称（驱逐持有它的死会话），设置 tmux 选项卡标题。每个 tmux 会话一个名称。 |
| `ipc_list_sessions` | — | 列出活动注册的会话；作为副作用，清理注册表中的死会话。 |
| `ipc_send` | `name`，`message` | 将消息传递到目标会话的输入框并提交。如果发送者未注册，或者目标是您或已死，则拒绝。 |
| `ipc_unregister` | — | 离开 IPC。 |
## 交付工作原理（以及为什么它很谨慎）
`ipc_send` 不是盲目的 `send-keys`。在注入之前，服务器：
1. **通过 TTY 查找调用者的身份**，而不是环境变量 — 它将 MCP 进程的 TTY 映射到 tmux 窗格（`tmux list-panes -a`），因此身份在陈旧/继承的 `TMUX_PANE` 值中存活下来。
2. **检查目标是否活动**（`tmux has-session`）并在不活动时将其从注册表中清理。
3. **使输入框可见** — 如果目标处于扩展视图（Ctrl-O 等），则发送 Escape 并等待 UI 重新渲染。
4. **等待人类** — 它捕获目标窗格 *带有 ANSI 颜色*，剥离克劳德代码的暗灰色占位符文本（颜色 246），并读取输入框中实际输入的内容。如果实际消息正在组成中（3+ 个字母的单词启发式；随机按键不计），它轮询最多 120 秒，直到用户提交，然后搭载。这就是防止代理破坏您正在输入的提示的原因。
5. **使用括号粘贴** 注入（`ESC[200~ … ESC[201~`），因此长多行消息作为一个输入到达，然后按 Enter。
详细信息在 [docs/how-it-works.md](docs/how-it-works.md) 中。有关在此基础上运行多代理团队的模式（单写入器 git、契约优先 ping、保持/继续纪律），请参见 [docs/agent-team-patterns.md](docs/agent-team-patterns.md)。
## 安全模型和限制
**信任模型：一个人类，一个机器。** 没有身份验证。任何可以写入您的 tmux 服务器的进程已经可以输入您的终端；此工具只是使克劳德会话的输入更加方便。后果：
- **接收的消息是提示。** IPC 消息作为用户输入提交，具有用户输入权限，到接收会话。只有在彼此信任对方键盘的会话中运行 IPC。不要将不受信任的内容直接连接到 `ipc_send`。
- **仅限 tmux。** tmux 外部的会话无法注册（服务器需要一个窗格来输入）。终端选项卡用户：`ipclaude` 处理包装。
- **仅限同一台机器。** 注册表是一个本地文件，交付是本地 tmux。没有网络传输。
- **交付是尽力而为。** 如果目标卡在权限对话框中，Escape 提示无法清除，或者 120 秒的搭载窗口在人类仍在输入时过期，注入可能会 awkward 地交错。实际上，这很少见；上述缓解措施涵盖了常见情况。
- **启发式跟踪克劳德代码的 TUI。** 占位符检测依赖于克劳德代码的暗灰色（256 色 246）样式和 `>` 提示。未来的克劳德代码重新设计可能需要更新 `server.py` 中的这些常量。
## 配置
| 环境变量 | 默认值 | 含义 |
|---|---|---|
| `CLAUDE_IPC_DIR` | `~/.claude/ipc` | `registry.json` 存放位置（服务器和启动器都遵循）。 |
| `IPCLAUDE_BIN_DIR` | `~/.local/bin` | `install.sh` 创建符号链接的位置。 |
## 卸载
```bash
claude mcp remove --scope user ipc
rm ~/.local/bin/ipclaude
rm -rf ~/.claude/ipc # 运行时状态（仅注册表）
```
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
