Skip to main content
Glama
deenesjakoruzh
guyiicn

pi-subagent

by guyiicn
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

pi-subagent

将 Pi CLI（@earendil-works/pi-coding-agent）变成一个可编程的编码子代理，任何 MCP 主机（ZCode、Claude Code、Cursor 等）都可以向其委派任务、跟踪会话并终止进程。

pi-subagent 是一个轻量级 MCP 服务器，它将 pi -p --mode json 封装为 7 个结构化工具：委派任务、收集结果、做出调度决策、管理命名会话以及中止运行。进程隔离、完全基于会话、同步/异步双模式。

为什么

Pi 是一个极简的终端编码代理。与其教 Pi 方法论，本项目将 Pi 视为一个可委派的工人：主机代理（ZCode / Claude Code）决定何时委派，发出一个自包含的任务，然后收集结果。一个 Pi 进程 = 一次隔离的子代理运行。

  • 进程隔离 — 每次委派都会生成一个 pi -p 子进程。Pi 崩溃只会影响该次运行。

  • 完全基于会话 — 每个任务都绑定到一个命名会话（例如 feat-auth）；后续调用自动继续。

  • 同步 / 异步 — 默认为 async（避免主机工具调用超时）；使用 pi_status 长轮询收集结果。

  • 可调度 — pi_plan 是一个纯 5 阶段决策函数（拒绝 / 容量 / 复用 / 修改 / 模式），完全单元测试。

  • 通用 MCP — 任何标准 MCP 客户端都可以加载它。

Related MCP server: cursor-agent-bridge

架构

┌─────────────────────────────────────────────────────────────┐
│  MCP Host (ZCode / Claude Code / Pi / Cursor …)              │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP (JSON-RPC over stdio)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  pi-subagent-server  (Node/TS)                                │
│  ┌────────────┐  ┌──────────────┐  ┌────────────────────┐   │
│  │ Tool layer │  │ Session      │  │ Pi runner          │   │
│  │ (7 tools)  │─▶│ registry     │─▶│ (spawn pi -p)      │   │
│  │ + plan()   │  │ + persist    │  │ parse agent_end    │   │
│  └─────┬──────┘  │ + _snapshot  │  │ + tool_execution   │   │
│        │         └──────────────┘  └─────────┬──────────┘   │
│        │                           ┌────────▼─────────┐     │
│        └───────────────────────────│ Run registry     │     │
│           (kill)                   │ + process-table  │     │
│                                   └──────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │ child_process.spawn({ cwd })
                            ▼
                   ┌─────────────────────┐
                   │  pi CLI (0.77+)     │
                   └─────────────────────┘

三层边界清晰：工具层（MCP 模式 + plan() 纯函数）/ 会话注册表（状态 + 持久化 + 脱敏）/ 运行器（生成 pi、解析 NDJSON、进程表）。

工具

工具

用途

pi_plan

决定：是否应委派、同步/异步、多少个会话

pi_delegate

派发任务（默认异步；新会话等待握手）

pi_status

收集运行结果（长轮询）

pi_session_list

列出会话（省略 cwd 以获取 pi_plan 所需的完整集合）

pi_session_snapshot

检查单个会话

pi_session_fork

分支一个会话以尝试另一条路径

pi_kill

中止运行

pi_task_create

创建多阶段任务（主机先写入 _plan-draft.md）

pi_task_plan

派发对计划的领域审查（通过 pi_status 收集，自动解析裁决）

pi_task_stage_run

运行一个阶段：同步（等待结果）或异步（返回 runId）

pi_task_stage_collect

收集异步阶段运行；自动判断并重新派发（最多 3 次），否则手动

pi_task_list

列出任务（按 taskId / 状态过滤）

审查循环：在 pi_task_plan 之后，使用 pi_status(runId) 收集结果。当运行完成时，服务器检测到这是审查运行，解析 _plan-reviewed.md，并将 planVerdict / planReviewedPath 存储在任务上。阶段提示自动包含已审查的计划和已通过依赖阶段的输出文件。

异步阶段：向 pi_task_stage_run 传递 mode: "async" 以避免阻塞工具调用整个运行（当 MCP 主机强制短工具超时时推荐）。使用 pi_task_stage_collect(taskId, stageId) 收集。失败的尝试会在新的会话名称下重新派发，以避免历史污染；3 次失败后，阶段进入 manual 状态，并显示决策面板（通过 promptHintOverride 支持 retry_with_new_hint）。

重启恢复：使用相同的 taskId 重新运行 pi_task_create 会合并而不是冲突。输出文件已存在且通过验证的阶段会自动标记为 passed，因此中断的任务无需手动编辑 tasks.json 即可恢复。

会话模型

  • 每个会话都有一个人类可读的名称 + Pi 的 UUID + cwd + goal。

  • 第一次 pi_delegate 创建会话（需要 goal）；后续调用自动继续。

  • 注册表持久化到 ~/.pi-subagent/registry.json（原子写入；重启时，中断的 running 记录会被纠正为 error）。

  • 并发上限：4 个正在运行的运行；单个会话永远不会并发运行。

  • 任务持久化到 ~/.pi-subagent/tasks.json（原子写入；重启时，正在运行的阶段会被纠正为 failed(interrupted_by_restart)）。

安装

git clone <this-repo> && cd pi-subagent
npm install

先决条件：pi CLI 已安装（npm i -g @earendil-works/pi-coding-agent）并在 PATH 中。

配置 MCP 主机

添加到您的 MCP 客户端配置：

{
  "mcpServers": {
    "pi-subagent": {
      "command": "npx",
      "args": ["tsx", "/abs/path/to/pi-subagent/src/server.ts"]
    }
  }
}

可选环境变量：

  • PI_SUBAGENT_REGISTRY — 注册表路径（默认 ~/.pi-subagent/registry.json）

  • PI_BIN — 覆盖 pi 可执行文件（用于测试）

测试

npm test           # full suite (140 tests)
npm run test:fast  # dot reporter

测试使用一个假的 pi（test/fixtures/fake-pi.sh），涵盖：异步/同步、超时、终止、会话创建失败、多等待者、进度上限、调度规则（表驱动 + 100 次迭代属性测试）、注册表持久化、脱敏等。

项目布局

src/
├── types.ts                 # all shared types + error codes
├── errors.ts                # ToolError helpers
├── runner/                  # parse.ts, argv.ts, spawn.ts, process-table.ts
├── registry/                # session.ts, run.ts, persist.ts, redact.ts
├── scheduler/               # keywords.ts, plan.ts (5-stage pure function)
├── tools/                   # delegate, status, plan-tool, session, kill
└── server.ts                # MCP entry (stdio)
skills/pi-subagent/          # SKILL.md + delegation-patterns (strategy layer)
test/                        # fixtures/ + *.test.ts
docs/                        # design.md (spec) + implementation-plan.md

设计与流程

本项目在实现之前经历了协作设计 + 4 轮外部审查。规范和计划已提交在 docs/ 下：

  • docs/design.md — 完整的设计规范（架构、工具契约、错误处理、调度器规则、测试策略）。每个契约都可追溯到审查注释（R1–R4）。

  • docs/implementation-plan.md — 19 个 TDD 任务（编写失败测试 → 实现 → 通过 → 提交）。

关键设计决策，均基于对 pi -p 输出的实际探测和外部审查：

  • cwd ≠ 会话存储 — spawn({ cwd }) 控制工作目录；Pi 的会话文件使用其默认位置（不污染项目）。

  • 异步默认 + 握手 — 新会话在返回之前等待 Pi 的 session 事件（带有 sessionStartTimeoutMs），因此主机始终获得真实的 piSessionId。

  • 多阶段调度器 — plan() 是拒绝 → 容量 → 复用 → 修改 → 模式，其中修饰符堆叠而不是首次匹配（来自审查第 1 轮的教训）。

  • 进度脱敏 — 工具结果在存储之前会被截断并清除令牌/密钥。

状态

可工作的实现，140 个通过的测试。尚未发布到 npm — 通过 tsx 从源码运行。

许可证

MIT

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
A
license - permissive license
C
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • ContextStream

    Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).

  • Kody

    Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.

  • agentmailrooms-mcp

    A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/guyiicn/pi-subagent'

If you have feedback or need assistance with the MCP directory API, please join our Discord server