English

Agents write great code, but long tasks often die on four things:

1. Plans miss key details — not what you actually need
2. Claims "done", but it's hallucinated
3. Poor delivery quality
4. Different models excel at different roles; one model doing everything underperforms

Pi Flow solves this: multi-round alignment → executable plan → live HTML report → multi-model adversarial checks → loop until quality ships.

Comparison

| | Pi Flow | Codex | Claude | |---|---|---|---| | Approach | Prompt injection · zero tool, pure UI prompt recognition | ❌ Tool injection | ❌ Tool injection | | Alignment | Clarify first, then plan | ❌ | ❌ | | Model roles | Separate planning, execution, and review models | ❌ | ❌ | | Acceptance | Multi-model cross-review, per-requirement verification | ❌ Player and referee | ❌ Small model | | Evidence | Requirements + plan + code + output + multi-model opinions | ❌ Player and referee | ❌ Conversation only | | Quality | Multi-agent read-only review, iterative optimization | ❌ | ❌ | | Orchestration | /flow chains + per-goal acceptance | ❌ | ❌ | | Reports | Live HTML report, step-level, traceable | ❌ | ❌ |

Highlights

• Zero tool injection — Pure prompt recognition, no agent tools, respects Pi's runtime
• Clarification-first — Clarifies before planning, unlike other agents that go with assumptions
• Role-based models — Separate planning, execution, and review models, so each model does what it is best at
• Multi-model acceptance — Cross-review, per-requirement verification, fewer false "done"s
• Multi-agent review — Read-only review, iterative optimization, no shortcuts
• Live reports — HTML step-level progress, runs locally, always traceable

Install

pi install npm:@surgee/pi-flow

If Pi is already running, restart it or run:

/reload

Requires Node.js >=22.19.0.

Configuration

Copy the template for local overrides:

cp config.template.json config.json

Model roles

config.template.json already includes modelRoles. Keep a role as "current" to use the model currently selected in Pi, or pin it to a specific { "model", "thinking" }.

{
  "modelRoles": {
    "planner": { "model": "52mx/free/glm-5.2", "thinking": "xhigh" },
    "executor": { "model": "openai-codex/gpt-5.5", "thinking": "xhigh" },
    "reviewers": [
      { "model": "openai-codex/gpt-5.4", "thinking": "high" }
    ]
  }
}

• planner — alignment and plan generation
• executor — implementation entry
• reviewers — completion acceptance and quality checks
• planner / executor may also be "current"

Recommended role models

• Planning — Claude Fable 5, Claude Ops 4.8, GLM 5.2
• Execution — Claude Fable 5, GPT-5.5
• Review — GPT-5.2, GPT-5.3 Codex, GPT-5.4, GLM 5.2, Kimi K2.7, DeepSeek V4, GPT-5.4 Mini
• Cost-performance benchmark →

| Key | Value | Description | |---|---|---| | generation.align | "ask" / "yes" / "no" | ask = ask each time; yes = always align; no = generate directly | | modelRoles.planner | "current" / role model | Model used for alignment and plan generation. Role model must use exact provider/model plus thinking | | modelRoles.executor | "current" / role model | Model used once when execution starts. Pi keeps the selected model afterward | | modelRoles.reviewers | model array | Models for acceptance and quality checks, each with model and thinking (off/minimal/low/medium/high/xhigh) | | models | model array | Legacy alias for modelRoles.reviewers; do not set both | | runner.command | "pi" | Child process CLI command | | runner.tools | tool name array | Tools available to child process, e.g. ["read","bash","grep"] | | runner.timeoutMs | milliseconds | Per-step timeout, default 1200000 (20 min) | | runner.serviceTier | "default" / "priority" | API service tier | | acceptance.enabled | true / false | Toggle completion acceptance | | quality.enabled | true / false | Toggle quality checks | | quality.mode | "autoFix" / "manual" | autoFix = auto-fix on failure; manual = report only |

30 seconds to start

/goal          # Single target: plan → execute → accept → quality check
/flow          # Multi-goal: chain goals, advance and hand off one by one
/review        # Quality-check AI operations

Inline request:

/goal Fix login state after refresh
/flow Refactor the login flow in safe steps

Markdown request file:

/goal task.md
/flow plan.md

Continue, cancel, status:

/goal continue | cancel | status
/flow continue | cancel | status

Target a previous item:

/goal status <id>
/goal start <id>
/flow status <id>
/flow start <id>

Delivery loop

Request → plan → execution → completion acceptance → quality check → close
                           ↘ keep fixing if a check fails ↙

• /goal — one focused target.
• /flow — massive work, multi-goal chain with per-goal plan / accept / report / handoff.
• Reports run at http://127.0.0.1:<port>.
• Completion acceptance: "Is the requirement truly done?"
• Quality checks: "Is the implementation clean, reliable, and maintainable?"

Co-create

Pi Flow is young and opinionated. If you care about more reliable agent delivery loops, ideas, issues, and focused PRs are welcome.

• Discuss — open an issue with the workflow you want to improve
• Contribute — read CONTRIBUTING.md and keep changes small

中文

Agent 很会写代码，但长任务常死在四件事：

1. 计划遗漏关键信息，不符合你真正的需求
2. 说自己做完了，实际上是幻觉
3. 完成质量差
4. 不同模型擅长不同角色，单模型硬扛效果不佳

Pi Flow 解决这个问题：多轮对齐需求 → 可执行计划 → 实时报告 → 多模型对抗检查 → 循环修复直至高质量交付

对比

| | Pi Flow | Codex | Claude | |---|---|---|---| | 实现 | Prompt 注入 · 零工具，纯 UI 提示符识别 | ❌ 工具注入 | ❌ 工具注入 | | 对齐 | 先追问澄清，再生成计划 | ❌ | ❌ | | 角色模型 | 计划 / 执行 / 审查分别指定模型 | ❌ | ❌ | | 验收 | 多模型交叉审查，按需求逐项反查 | ❌ 既当球员又当裁判 | ❌ 小模型 | | 证据 | 需求 + 计划 + 代码 + 输出 + 多模型意见 | ❌ 既当球员又当裁判 | ❌ 只看对话 | | 质量 | 多代理只读审查，循环优化 | ❌ | ❌ | | 编排 | /flow 串联 + 逐目标验收 | ❌ | ❌ | | 报告 | 实时 HTML 报告，步骤级可回溯 | ❌ | ❌ |

亮点

• 零工具注入 — 纯 Prompt 识别，不加 agent tool，不侵入 Pi 运行时
• 追问对齐 — 先澄清再计划，不像其他 Agents 靠自己的想当然发挥
• 角色模型 — 计划、执行、审查分别指定模型，让合适的模型做擅长的事
• 多模型验收 — 交叉审查，按需求反查，减少"假完成"
• 多代理审查 — 只读审查，循环优化，不偷懒、不遗漏
• 实时报告 — HTML 步骤级进度，本地运行，随时回溯

安装

pi install npm:@surgee/pi-flow

如果 Pi 已经在运行，重启或执行：

/reload

需要 Node.js >=22.19.0。

配置

复制模板作为本机配置：

cp config.template.json config.json

模型角色

config.template.json 已包含 modelRoles。某个角色写 "current" 就沿用 Pi 当前模型；写 { "model", "thinking" } 就固定到指定模型。

{
  "modelRoles": {
    "planner": { "model": "52mx/free/glm-5.2", "thinking": "xhigh" },
    "executor": { "model": "openai-codex/gpt-5.5", "thinking": "xhigh" },
    "reviewers": [
      { "model": "openai-codex/gpt-5.4", "thinking": "high" }
    ]
  }
}

• planner：追问对齐、生成计划
• executor：进入执行时使用
• reviewers：完成验收和质量检查
• planner / executor 也可以写 "current"

推荐角色模型

• 计划模型 — Claude Fable 5、Claude Ops 4.8、GLM 5.2
• 执行模型 — Claude Fable 5、GPT-5.5
• 审查模型 — GPT-5.2、GPT-5.3 Codex、GPT-5.4、GLM 5.2、Kimi K2.7、DeepSeek V4、GPT-5.4 Mini
• 综合性价比 benchmark →

| 配置 | 值 | 说明 | |---|---|---| | generation.align | "ask" / "yes" / "no" | ask＝每次询问；yes＝总是先对齐；no＝直接生成 | | modelRoles.planner | "current" / 角色模型 | 对齐和生成计划时使用；角色模型必须写精确 provider/model 和 thinking | | modelRoles.executor | "current" / 角色模型 | 执行开始时切一次；之后保留 Pi 当前选择 | | modelRoles.reviewers | 模型数组 | 完成验收和质量检查用的模型，每项含 model 和 thinking（off/minimal/low/medium/high/xhigh） | | models | 模型数组 | 旧配置别名，等同 modelRoles.reviewers；不要同时配置 | | runner.command | "pi" | 子进程 CLI 命令 | | runner.tools | 工具名数组 | 子进程可用工具，如 ["read","bash","grep"] | | runner.timeoutMs | 毫秒数 | 单步超时，默认 1200000（20 分钟） | | runner.serviceTier | "default" / "priority" | API 服务等级 | | acceptance.enabled | true / false | 开关完成验收 | | quality.enabled | true / false | 开关质量检查 | | quality.mode | "autoFix" / "manual" | autoFix＝不过自动修；manual＝只报告 |

30 秒开始

/goal          # 单目标：计划 → 执行 → 验收 → 质量检查
/flow          # 多目标：串联多个 goal，逐个推进并交接
/review        # 对 AI 操作做质量检查

直接带需求：

/goal 修复刷新后的登录状态
/flow 重构登录流程，分步骤安全推进

把 md 文件作为需求：

/goal task.md
/flow plan.md

继续、取消、状态：

/goal continue | cancel | status
/flow continue | cancel | status

指定历史目标：

/goal status <id>
/goal start <id>
/flow status <id>
/flow start <id>

工作流程

对齐 → 计划 → 执行 → 完成验收 → 质量检查 → 收口
                   ↘ 不通过则循环修复 ↙

• 对齐："多轮问答全面挖掘你的需求"
• 完成验收："确保任务完整完成，无偷懒"
• 质量检查："确保实现干净、可靠、可维护"

共创

Pi Flow 还在快速迭代。如果你也在探索更可靠的 Agent 循环，欢迎一起打磨。

• 讨论 — 用 issue 描述你的工作流和痛点
• 贡献 — 先读 CONTRIBUTING.md，保持改动小而清晰

License

Apache-2.0. See LICENSE.