ButtInChat

让多个 AI Agent CLI（Claude Code、Codex CLI、OpenCode 等）之间互相插话：发现彼此、互相提问、广播通知，组成一个可协作的多 agent 工作组。

架构

Hub daemon (/tmp/buttinchat.sock)
  - 会话注册表
  - 消息路由
  - inbox / reply 存储

PTY Wrapper
  - 启动 agent
  - 写入本地 .buttinchat.session，记录 agent PID 和 launch 信息
  - 轮询 inbox
  - 把 ButtInChat request 注入到 agent stdin

Skill
  - 告诉 agent 启动后先 register
  - 告诉 agent 看到 request_id 后必须执行 buttinchat reply

回复是显式协议：agent 收到带 request_id 的注入消息后，必须运行 buttinchat reply --to <request_id> "答案"。

快速开始

# 1. 启动 Hub
buttinchat hub start

# 2. 给所有已知 agent 安装 skill 软链接
buttinchat init

# 3. 启动托管 agent（内置快捷入口）
buttinchat claude --name frontend --tags react,ui
buttinchat codex --name backend --tags go,api
buttinchat opencode --name worker --tags opencode

快捷入口会自动选择对应 CLI；需要传 agent 自己的参数时放在 -- 后面：

buttinchat codex --name backend -- --model gpt-5
buttinchat claude --name frontend -- --model sonnet

也可以继续使用通用 launch：

buttinchat launch --agent-type codex --name backend
buttinchat launch --name custom -- custom-agent --flag

launch 和内置快捷入口都不直接注册完整 session。它们会在当前项目写 .buttinchat.session，记录启动的 agent PID、agent type、工作目录和默认 name/tags。agent 根据 skill 执行：

buttinchat register --name frontend --tags react,ui --agent-type claude

register 会自动读取 .buttinchat.session，把注册信息和 launch PID 一起发送给 Hub，并把返回的 session_id 写回 .buttinchat.session。之后 send、reply、inbox 会自动读取这个 session id。

卸载会清理 ButtInChat skill 软链接：

buttinchat uninstall
buttinchat uninstall --agent codex

通信

同步提问：

buttinchat ask --target backend --timeout 30 "API 列表？"

异步提问：

req_id=$(buttinchat send --target backend "GET /users 返回字段是什么？")
buttinchat check-reply --id "$req_id"

收件和回复：

buttinchat inbox
buttinchat reply --to <request_id> "答案"

广播：

buttinchat broadcast --tag all "主分支已合并，请同步"

注入格式

wrapper 会把 inbox 消息注入成类似格式：

[ButtInChat request]
from: backend
request_id: 00000000-0000-0000-0000-000000000000

问题正文

After you finish, send the answer back by running:
buttinchat reply --to 00000000-0000-0000-0000-000000000000 "<your answer>"

Do not answer only in chat; the sender receives replies only through buttinchat reply.

已安装的 skill 会提醒 agent 必须通过 buttinchat reply 回传结果。

命令一览

命令	说明
buttinchat hub start	启动 Hub
buttinchat hub stop	停止 Hub
buttinchat init [--agent x]	安装 skill 软链接
buttinchat uninstall [--agent x]	清理 skill 软链接
buttinchat claude --name <name>	托管启动 Claude Code 并写 .buttinchat.session
buttinchat codex --name <name>	托管启动 Codex CLI 并写 .buttinchat.session
buttinchat opencode --name <name>	托管启动 OpenCode 并写 .buttinchat.session
buttinchat launch --name <name> [-- <cmd>]	通用托管启动入口
buttinchat register --name <name>	agent 自注册，并绑定 launch PID
buttinchat status	列出在线会话
buttinchat discover [--tag x]	查找会话
buttinchat ask --target <name> "问题"	阻塞提问
buttinchat send --target <name> "问题"	异步提问并返回 request_id
buttinchat check-reply --id <request_id>	检查异步回复
buttinchat inbox	查看待回复消息
buttinchat reply --to <request_id> "答案"	回复消息
buttinchat broadcast --tag <tag> "消息"	广播消息

Skill

buttinchat init 会把 skill/SKILL.md 软链接到对应 agent 的 skill 目录：

• Claude: ~/.claude/skills/buttinchat/SKILL.md
• Codex: ~/.codex/skills/buttinchat/SKILL.md
• OpenCode: ~/.config/opencode/skills/buttinchat/SKILL.md

如果安装时找不到仓库里的 skill/SKILL.md，二进制会把内嵌 skill 写入 ~/.buttinchat/SKILL.md，再链接到各 agent。

项目布局

cmd/buttinchat/        # CLI 入口与 subcommand
internal/agents/       # Agent CLI 适配层
internal/hub/          # Hub daemon、Router、Session 管理
internal/protocol/     # IPC 协议、客户端、轮询器
internal/pty/          # PTY 封装
internal/tui/          # PTY wrapper 和消息注入
skill/SKILL.md         # 给 agent 用的技能文档

扩展新 Agent

新增 adapter 实现：

type Adapter interface {
    Type() string
    DefaultCommand() []string
    SkillLinkPath() string
}