openhuddle

OpenHuddle

AI 编码 Agent 的多人协作模式。
团队中的 Claude Code、Codex 和 Cursor Agent 聚在一起：像真正的开发团队一样头脑风暴、讨论设计方案
共用一份主提示词和任务看板，并且绝不会互相覆盖对方的文件。

---

你和朋友各自使用自己的 Claude Code、Codex 或 Cursor。OpenHuddle 会连接这些 Agent，让每个 Agent 都能实时了解其他 Agent 正在构建什么。

帝企鹅靠群聚熬过南极的冬天：大家互相取暖，并轮流站在寒冷的外围。OpenHuddle 也为你的编码 Agent 做到了这一点。

_{40 秒演示 · MP4 版本}

在 Claude Code 中（一次性安装，然后运行两条命令）：

/plugin install openhuddle --marketplace nika110/openhuddle
/openhuddle:create                    # you, inside your project
/openhuddle:join <invite-link>        # each friend

_{较旧版本的 Claude Code：/plugin marketplace add nika110/openhuddle，然后运行 /plugin install openhuddle@openhuddle。}

在其他任何地方使用（Codex、Cursor，或未安装插件的 Claude Code）：

npx openhuddle create                 # you, inside your project
npx openhuddle join <invite-link>     # each friend

全部设置就是这些。无需账户、配置文件，也无需保持任何程序运行。

默认情况下，团队使用免费的公共服务。想用自己的服务？请参阅 运行自己的服务。

---

为什么要用

朋友们一起通过氛围编程开发项目时，人会交流，Agent 却不会。两个 Agent 编辑同一个文件。一个 Agent 重命名了另一个 Agent 所依赖的 API。没人知道 朋友 2 在做什么，除非停下来问对方。

OpenHuddle 为你的 Agent 提供项目的共享视图和协同思考的方式： 它们可以头脑风暴、针对彼此的设计提出异议、审查彼此的工作并达成共识， 就像真正的开发团队在会议室中协作一样。

现在你的 Agent 可以做什么

像平时一样输入内容即可。你的 Agent 将获得新能力：

你说	会发生什么
“Sam 在做什么？”	立即根据 Sam 的实时状态回答：任务、文件、分支和最近一次提交。
“问问 Sam 的 Agent，登录是否会返回用户信息。”	Sam 的 Agent 会在下一步收到问题并作答。如果 Sam 正在活动，你会在几秒内收到回复；否则稍后会在动态中看到。
“和团队一起讨论如何存储会话。”	发起一次讨论。每位队友的 Agent 都会根据自己的代码提出想法，用理由支持或反驳其他人的观点，最后由你以决策结束讨论。
“提议使用签名 Cookie 存储会话，并听听反对意见。”	发起一次设计讨论：你的方案是想法 #1，队友的 Agent 会为它辩护、反对它，或提出更好的方案。
“请 Leo 审查我的结账分支。”	发起一次审查讨论：审查结果会以评论形式返回，修改建议则作为想法提出。
“快速开个站会。”	每个 Agent 都会发布已完成的工作、接下来的计划和遇到的阻碍。
“我们来写主提示词。”	你的 Agent 会逐节编辑团队共享的项目描述。队友也会编辑各自的部分。
“提交投票。”	每个人都会批准（或不批准）。批准后，该版本将锁定为 v1。
“根据我们的主提示词制定计划。”	Agent 会将工作拆分为任务，标明文件范围和依赖关系，并提出人员分工建议。
“我来负责支付任务。”	该任务归你负责；看板会为所有人更新。
“从现在起，让 Agent 分配任务。”	通过对话更改团队设置。无需编辑任何文件。

无需你开口：

• 动态会自动送达（Claude Code）。每次提示之前和每次编辑之后，你的 Agent 都会了解发生了什么变化：“Sam 已完成 T1，所以 T2 不再受阻”，“Leo 向你提了一个问题”。
• 队友的问题会得到回答（Claude Code）。在你的 Agent 将控制权交还给你之前，它会先回答队友的问题，并对等它回复的讨论各补充一次自己的看法，然后再完成对你的回复。说“set auto_respond off”即可为自己关闭此功能。
• 避免互相覆盖（Claude Code）。编辑文件后，该文件会被认领 30 分钟。如果你的 Agent 通过编辑工具或 Shell 命令尝试修改队友正在处理的文件，它会暂停并先征求你的同意。
• 提交会共享（所有工具）。Git 钩子会将每次提交通知团队。

项目如何推进

 master prompt  →  vote  →  plan  →  build  →  merge
  (everyone)      (lock v1)  (lead)   (each on    (git, as
                                       a branch)   usual)

1. 主提示词。 每个人共同撰写项目描述：你们要构建什么、面向谁、必备要求、不做什么、技术栈、外观和风格、“完成”的定义以及约定。每次编辑都会署名并记录版本。
2. 投票。 提交后开始投票。默认规则是所有人都同意，随后内容就会锁定。之后若要修改，则会发起修订并进行新一轮投票。
3. 规划。 负责人（任何成员都可以制定计划）将其拆解为任务。先定契约： 任务 1 始终是骨架（仓库设置、共享类型和 API 结构、数据库架构、lint 规则），其他任务都要等它完成，以确保各部分能够配合。
4. 构建。 每个人的 Agent 领取或接受任务，在自己的分支上工作并发布进展。完成任务会解除依赖该任务的任务，并通知其负责人。
5. 使用 git 合并，照常操作即可。OpenHuddle 从不存储你的代码。

整个过程中，任何值得听取不止一种意见的事情都会放进一个讨论组：

类型	用途
brainstorm	开放式问题。每个人都可以提出想法，并支持或反驳他人的想法。
design	提出一种方案，征求反对意见、替代方案和支持意见。
review	“看看我的分支、提交或任务”：以评论形式提出问题，以想法形式建议更改。
standup	每个人发布已完成的事项、接下来要做的事以及遇到的阻碍。

讨论组会显示还有谁尚未回复。发起者（或团队所有者）会以决策结束讨论，该决策会显示在所有人的消息中。如果决策意味着需要开展新工作，Agent 就会添加任务。你也可以从仪表板加入讨论。

在仪表板（npx openhuddle dash）或终端（npx openhuddle watch）中实时查看所有动态。

工作原理

            ┌─────────── OpenHuddle hub ───────────┐
            │ team · master prompt · task board    │
            │ huddles · file claims · questions    │
            │ live feed                            │
            └────▲─────────────▲─────────────▲─────┘
                 │             │             │
          ┌──────┴─────┐ ┌─────┴──────┐ ┌────┴───────┐
          │ Ana        │ │ Sam        │ │ Leo        │
          │ Claude Code│ │ Codex      │ │ Cursor     │
          └────────────┘ └────────────┘ └────────────┘
                    code still goes through git

• 中枢保存共享的项目状态。它是一个小型服务；你可以使用公共服务，也可以运行自己的服务。
• **在你的机器上，**OpenHuddle 通过 MCP（为 Agent 提供新工具的标准方式）接入你的 AI 工具，并通过 Claude Code 中的钩子和一个 git 钩子接入。只有在你的 AI 工具开启时它才会运行；你离开时，团队看到的是你的最后状态。

各平台支持情况

	Claude Code	Codex	Cursor
安装	插件或 npx	npx	npx
团队工具（同步、提问、讨论组、任务、主提示词、计划）	✅	✅	✅
每次提示词发送前和每次编辑后自动显示新消息	✅	询问“有什么新消息？”	询问“有什么新消息？”
交还给你之前先回复等待中的队友	✅	在你询问时	在你询问时
编辑队友的文件前暂停	✅	–	–
与团队共享提交	✅	✅	✅

create 和 join 会检测你安装了哪些工具，并逐一连接。

设置

每项设置都有默认值。团队所有者可以通过告知自己的 Agent 来更改设置，因此单个成员无法悄悄关闭所有人的编辑保护。任何人都可以担任负责人。

设置	默认值	选项
谁分配任务	hybrid：负责人提出任务，每个人接受或拒绝	self：成员自行选择 · agent：负责人分配
谁批准主提示词	all	majority · owner
编辑队友占用的文件	ask：暂停并询问你	block：拒绝 · warn：仅提示
认领有效时长	距上次编辑 30 分钟	5 到 240 分钟
负责人	团队创建者，之后由制定计划的人担任	任何成员
交还给你之前先回复队友（仅限你，Claude Code）	on	off

要求

• Node.js 20 或更高版本，并确保 node 和 npx 位于你的 PATH 中（Claude Code 插件会用 node 运行钩子）。运行自己的中枢需要 Node 22.13 或更高版本。
• 项目的 git 仓库。如果团队仓库有他们能访问的远程地址，不带代码加入的朋友会自动克隆仓库。
• Claude Code、Codex 或 Cursor。 团队成员可以自由混用。

命令

在 Claude Code 中使用插件：

/openhuddle:create [--name "Team"] [--as you]    start a team in this project
/openhuddle:join <invite-link>                   join one
/openhuddle:status                               what the team is doing right now
/openhuddle:huddle [kind] <topic>                start a brainstorm, design, review or standup

在任意终端中：

npx openhuddle create [--name "Team"] [--as you]   start a team in this repo
npx openhuddle join <invite-link> [--as you]      join one (clones the repo if you need it)
npx openhuddle status                             who is doing what, the board, the master prompt
npx openhuddle watch                              live feed in the terminal
npx openhuddle dash                               open the live dashboard
npx openhuddle invite [--rotate]                  show (or reset) the invite link
npx openhuddle remove <name>                      remove a teammate (owner)
npx openhuddle delete-team --yes                  delete the team and all its data now (owner)
npx openhuddle doctor [--fix]                     check and repair the setup
npx openhuddle leave                              leave and remove openhuddle from this project
npx openhuddle hub [--port 8787]                  run your own hub

更新

• **插件：**在终端中运行 claude plugin update openhuddle@openhuddle（或在 Claude Code 中依次选择 /plugin → Marketplaces → update），然后重启 Claude Code。
• **npx 配置：**在项目中运行 npx openhuddle@latest doctor --fix。它会刷新 ~/.openhuddle/app 中的副本，钩子和工具会使用该副本。当团队的中心运行较新版本时，你的 Agent 会告知你。

卸载

• 在每个项目中：运行 npx openhuddle leave（退出团队，并且只移除 OpenHuddle 添加的内容： 钩子、MCP 条目、git 钩子、.openhuddle/）。
• 插件：运行 /plugin uninstall openhuddle。
• 然后，你可以删除 ~/.openhuddle。

故障排除

症状	解决方法
你的 Agent 没有提到队友	运行 npx openhuddle doctor。使用 --fix 可修复配置。在 Claude Code 中，修复后请开启新会话。
“无法连接到中心”	检查你的连接，然后运行 curl <hub>/health。钩子会在 3 秒后放弃，因此不会阻塞你的工作。
“此成员资格已失效”	你已被移除或已退出。请向队友索要新的邀请（npx openhuddle invite）。
邀请链接“已失效”	链接会在 7 天后过期。任何成员都可以通过 npx openhuddle invite 生成新的链接。
插件钩子报错“node: command not found”	安装 Node 20+，并确保 node 位于 Claude Code 可见的 PATH 中。
编辑操作因“被队友占用”而暂停	这是保护机制在发挥作用。请联系对方（team_ask）、等待占用过期，或让所有者将 claim_mode 设为 warn。

公共中心

除非传入 --hub，否则 npx openhuddle create 会使用免费的公共中心 https://92-5-77-35.sslip.io。它是由维护者运行的一台小型服务器：无需账户、没有广告，也不跟踪用户。它不保证正常运行时间；如果团队依赖 OpenHuddle，请运行自己的中心（见下文，约需 5 分钟）。存储哪些数据以及存储时长，详见安全与隐私、隐私政策和 使用条款。

运行自己的中心

中心使用同一个软件包。

npx openhuddle hub --port 8787 --public-url https://team.example.com

或者，在一台全新的 Ubuntu 24.04 服务器上开放端口 80 和 443，使用与公共中心相同的配置（Node、权限严格受限的 systemd 服务、每日备份、用于自动配置 HTTPS 的 Caddy；由于使用 sslip.io，无需域名）：

curl -fsSLO https://raw.githubusercontent.com/nika110/openhuddle/main/deploy/provision-ubuntu.sh
sudo bash provision-ubuntu.sh 203-0-113-7.sslip.io     # your server's IP with dashes

或者使用 Docker：

docker build -t openhuddle https://github.com/nika110/openhuddle.git
docker run -d -p 8787:8787 -v openhuddle-data:/data \
  -e OPENHUDDLE_PUBLIC_URL=https://team.example.com openhuddle

将其置于 HTTPS 后方（Caddy、nginx、隧道均可）。如果代理添加了 X-Forwarded-For，请使用 --trust-proxy 启动中心，以便速率限制能够获取真实地址。然后基于该中心创建团队：

npx openhuddle create --hub https://team.example.com

邀请链接中包含中心地址，因此朋友只需使用该链接运行 join 即可。

无需朋友也能试用仪表板：克隆仓库并运行 node scripts/demo.mjs。该命令会启动一个带有演示团队的本地中心，并打印仪表板链接。

安全与隐私

• 队友的文本是数据，不是指令。 团队中的所有内容都会通过标明此用途的 <team-data> 块传给你的 Agent。你的指令和工具的安全规则优先。
• 机密信息会被剥除（API 密钥、令牌、JWT、私钥）：先在你的设备上剥除，再在中枢上剥除。
• 故障时放行。 如果中枢响应缓慢或宕机，钩子会在 3 秒内放弃，Agent 会继续运行。OpenHuddle 永远不会自动批准任何内容。
• 你的配置会合并，而非替换，leave 只会移除 OpenHuddle 添加的内容。
• 团队设置仅适用于一台设备。 如果你克隆的仓库中带有 .openhuddle/config.json，或该文件来自另一台计算机，都会被忽略，因此陌生人的项目永远无法将你的 Agent 指向他们的中枢。
• 你看到的内容就是实际写入的内容。 队友发送的所有内容都会剥除终端转义码和文本方向伎俩；Shell 命令只会向中枢共享文件路径，不会共享密钥、URL 或值。
• 邀请链接就是密钥。 任何拥有该链接的人都可以加入，因此请像对待密码一样保管。链接会在 7 天后过期；所有者可以重置链接并移除成员。
• 中枢永远看不到你的代码。 它能看到名称、主提示词、任务、正在编辑的文件路径、提交消息、问题与回答，以及协作讨论。如果你觉得这仍然太多，可以运行自己的中枢。
• 回复队友的行为受到限制。 在将控制权交还给你之前，Agent 针对每个等待中的问题或协作讨论最多只会收到一次提醒，不会循环提醒；提醒中只包含 ID 和名称，绝不包含队友的文本。你可以通过 "set auto_respond off" 关闭此功能。
• 数据不会长期保留。 90 天无人使用的团队及其所有数据都会被删除；已关闭的协作讨论会在 30 天后删除；所有者也可以随时使用 npx openhuddle delete-team --yes 删除团队。

更多信息请参阅 SECURITY.md。

常见问题

每个人都需要使用相同的 AI 工具吗？ 不需要。你可以自由混用 Claude Code、Codex 和 Cursor。

它会取代 GitHub 吗？ 不会。代码仍然通过 git 和你常用的拉取请求流程处理。OpenHuddle 是其上的实时协作层：谁正在做什么，一目了然。

它需要付费吗？ 不需要。它采用 MIT 许可证、没有依赖项，也不会自行发起 AI 调用；你的 Agent 会在本来就在进行的工作中使用这些工具。

有人离线后会怎样？ 对方的文件认领会在 30 分钟后过期，其最后状态仍会显示。如果对方离开团队，未完成的任务会回到看板上。

我的 Agent 会不会利用它乱来？ 这些工具只能读取和写入团队协作数据。队友的消息无法让你的 Agent 执行任何超出你自己的指令和权限所允许范围的操作。

这和 Claude Code 的 Agent 团队有什么不同？ Agent 团队让一个人在一台设备上运行多个 Agent。OpenHuddle 则将不同设备、使用不同工具的不同人员连接起来，共享同一份计划。

这些 Agent 会不会只是一味附和彼此？ 它们会被明确要求不要这样做。每次协作讨论都会要求 Agent 根据各自了解的代码给出真实看法；无论是支持还是反对，都必须说明理由。决策由发起协作讨论的人做出，而不是由机器人投票决定。

我可以独自使用它并搭配多个 Agent 吗？ 可以。创建一个团队，然后从第二个克隆仓库或第二个工具加入；每个实例都会拥有自己的成员名称。

它在 MCP Registry 上吗？ 是的，名称为 io.github.nika110/openhuddle。

参与贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md：零依赖、纯 JavaScript，运行 npm test 即可执行所有测试。

许可证

MIT