sub-pi-agent 把 Pi 包装成独立的 stdio MCP 服务，供 Codex 及其他 MCP 客户端调用。主代理可以把模块检查、代码修改或测试任务交给具名的 Pi 子代理，自己继续规划与审查；需要补充信息或返工时，再回到同一会话，减少重复交代背景。

项目基于 Courtney Andrew Richardson 的 agent-pi 1.8.0 二次开发，保留原版 MIT 许可，在此基础上增加持久化会话、提问交回、未读事件与等待机制，并整理成独立 MCP/npm 入口。当前仓库版本为 0.1.1。来源说明

核心能力

  • 可复用的命名会话：为代理设置名字、说明和项目目录，按状态或目录查找；释放运行资源或重启 MCP 后，仍可显式继续原有上下文。
  • 把问题交回主代理：子代理通过 ask_supervisor 提交阻塞问题，进入 needs_input 状态；主代理读取问题后，使用同一会话 ID 回答并续接任务。
  • 运行中纠偏与后续任务：分别提供 steering 和 follow-up 队列，让补充指令在适当阶段进入 Pi 会话；排队成功与实际执行保持明确区分。
  • 有界等待：等待工具在 MCP 进程内检查状态，遇到完成、提问、错误或中断时返回；默认等待三分钟，最长五分钟，等待本身不调用模型，超时也不会停止任务。
  • 清晰的结果与生命周期：进度读取、最终交付和未读提醒各有入口；支持终止、释放和闲置回收，释放只卸载资源，保留会话与结果。工具参考

技术实现

技术栈为 TypeScript、Node.js、MCP SDK 与 Pi SDK。服务直接调用 Pi SDK，复用 Pi 的模型设置和认证配置，使用原生 SessionManager 保存对话。代理注册信息通过临时文件与重命名写入磁盘，同一会话使用进程租约协调写入，避免两个 MCP 实例同时继续同一已加载会话。

这套设计把任务身份、运行状态和持久上下文分开处理，也区分了“收到最新进度”与“读取最终交付”，为多代理协作提供明确的调用契约。数据与生命周期

当前使用边界

运行需要 Node.js ≥22.19.0 及已配置模型的 Pi 环境。子代理以启动 MCP 的本机用户权限访问文件、执行命令，没有独立沙箱。MCP 退出会中断正在执行的任务，恢复需要显式继续；系统没有反向实时通知，上层聊天结束后不会自动唤醒主代理。

GitHub · 安装与配置 · npm

开发记录：让 Codex 指挥 Pi 的 MCP