hivemind

<p align="center"> <img src="./docs/hivemind-logo.png" alt="Hivemind logo" width="200" /> </p> <h1 align="center">Hivemind</h1> <p align="center"> <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a> <a href="./package.json"><img alt="Version" src="https://img.shields.io/badge/version-0.1.0-green.svg" /></a> <a href="https://bun.sh"><img alt="Runtime: Bun" src="https://img.shields.io/badge/runtime-Bun-fbf0df.svg" /></a> <a href="./tsconfig.json"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178C6.svg" /></a> <a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://img.shields.io/badge/MCP-1.29-9146FF.svg" /></a> <a href="https://docs.anthropic.com/claude-code"><img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-plugin-D97757.svg" /></a> <a href="https://github.com/openai/codex"><img alt="Codex" src="https://img.shields.io/badge/Codex-app--server-10A37F.svg" /></a> </p> 在同一台机器上连接Claude Code和Codex。向Codex征求第二意见，在两个模型之间进行头脑风暴，或者直接从Claude调用Codex，所有这些都不需要复制/粘贴。 > **状态：** v0.1。单机，单Claude ↔ 单Codex。仅拉取模型（Claude发起）。Codex的推送式通知延期。 --- ## 工作原理 ``` Claude Code ──MCP──▶ 桥接 ──WS──▶ 守护进程 ──WS 代理──▶ codex 应用服务器 ▲ │ （WS 代理） ▼ Codex TUI ``` - **桥接** 在Claude Code内部作为MCP标准输入/输出服务器运行。它公开了`ask_codex`、`wait_for_codex`、`peers`、`get_messages`。 - **守护进程** 在后台运行。它拥有坐在Codex TUI和`codex app-server`之间的代理。代理拦截代理消息，并让Hivemind将提示注入到实时线程中。 - 守护进程在Claude重启后存活，并在60秒内没有桥接连接时空闲关闭。 --- ## 安装 ```bash git clone https://github.com/abderrahimghazali/hivemind.git cd hivemind bun install bun run build bun link # 在您的PATH上公开`hm`和`hivemind` ``` 您需要已经在 `$PATH` 上安装`claude` 和 `codex`。 --- ## 用法 在一个终端中，通过代理启动Codex： ```bash hm codex ``` 这将启动守护进程（幂等），启动`codex app-server`，并启动指向代理的Codex TUI。在Codex中发送任何消息 - 这将创建Hivemind可以针对的线程。 在另一个终端中，使用加载了Hivemind插件的Claude启动： ```bash hm claude ``` 现在，从Claude内部： | 斜杠命令 | 功能 | |---|---| | `/hivemind:peers` | 列出连接的对等体、线程、警告 | | `/hivemind:second-opinion <问题>` | 询问Codex，然后总结Codex的观点 + Claude的观点 + 建议 | | `/hivemind:brainstorm <主题>` | 三轮来回，然后进行综合 | 或在对话中直接调用MCP工具： > 使用 `mcp__hivemind__ask_codex`，带有 `text: "..."` 和 `wait_ms: 60000` ### MCP 工具 - `ask_codex({ text, wait_ms? })` — 将提示注入Codex线程。如果 `wait_ms > 0`，则阻塞直到回合完成（或超时）并返回回复。否则立即返回，回复通过 `wait_for_codex` 到达。 - `wait_for_codex({ timeout_ms? })` — 阻塞直到Codex发送消息，或如果有缓冲消息，则立即排空。 - `peers({})` — 列出对等状态。如果Codex打开了选择器（仅Hivemind v0.1支持新会话），则报告`unsupported_session_picker`警告。 - `get_messages({})` — 非阻塞排空缓冲消息。 --- ## 其他命令 ```bash hm status # 守护进程健康状况、线程ID、队列深度 hm logs -f # 跟踪守护进程日志 hm kill # 停止守护进程并写入"killed"信号文件 hm dev # 在前台运行守护进程（日志输出到stderr） ``` `hm kill`写入一个信号文件，以防止桥接自动重启守护进程。`hm codex` 清除它。 --- ## 配置 | 环境变量 | 默认值 | 用途 | |---|---|---| | `CODEX_WS_PORT` | `4600` | Codex应用服务器监听的端口 | | `CODEX_PROXY_PORT` | `4601` | Codex TUI连接的端口（Hivemind代理） | | `HIVEMIND_CONTROL_PORT` | `4602` | 桥接 ↔ 守护进程控制通道使用的端口 | | `HIVEMIND_IDLE_SHUTDOWN_MS` | `60000` | 空闲超时时间，守护进程在此超时后关闭 | | `HIVEMIND_STATE_DIR` | macOS: `~/Library/Application Support/Hivemind`; Linux: `$XDG_STATE_HOME/hivemind` | pid/日志/锁文件存储位置 | --- ## 限制 - **仅支持新建会话。** 如果Codex打开会话选择器（例如，您直接启动了`codex`而没有使用`hm codex`，然后再连接），Hivemind会检测到它，并且`ask_codex`返回`PICKER_DETECTED`。运行`hm kill && hm codex`以重置。 - **一次只能有一个Codex线程。** 多个TUI连接不允许多路复用。 - **仅拉取。** Codex无法主动通知Claude。Claude必须询问。 - **Codex无git写入。** 桥接合约提醒Codex不要运行`git commit/push/checkout -b/...` — 这些操作在Codex沙箱中挂起。只读git没问题。 --- ## 开发 ```bash bun run typecheck # tsc --noEmit bun run test # bun test src bun run check # 以上两个命令 bun run build # 打包dist/cli.js, dist/daemon.js, plugins/hivemind/server/{bridge,daemon}.js bun run dev # 前台运行守护进程（或：hm dev） ``` 代理的协议逻辑（`processTuiPayload`、`handleAppServerPayload`、`injectMessage`）是纯粹的，与I/O无关 - 请参见`src/codex-proxy.test.ts`中的fixture测试，涵盖id重写、过时连接断开、桥接id消耗、注入门控和代理消息提取。 ### 布局 ``` src/ bridge.ts # 前台入口：MCP服务器 + 守护进程客户端 daemon.ts # 后台入口：控制WS + Codex代理 codex-proxy.ts # 带有JSON-RPC id重写的WS代理（可测试的核心） daemon-client.ts # 桥接 → 守护进程WS客户端 daemon-lifecycle.ts # pid/锁/健康/启动 claude-mcp.ts # MCP工具定义和处理程序 control-protocol.ts # 桥接 ↔ 守护进程消息类型 codex-protocol.ts # codex JSON-RPC类型 + 守卫 bridge-contract.ts # 桥接合约提醒 cli.ts, cli/*.ts # `hm`子命令 plugins/hivemind/ # Claude Code插件（命令，.mcp.json，捆绑服务器/） ``` --- ## 许可证 MIT。参见 [LICENSE](./LICENSE)。