@2008muyu/pi-plan

Configurable two-phase planning workflow for pi coding agent. Plan with a strong model, execute with a light model — all models fully configurable.

中文版

Why?

Existing plan-mode extensions hardcode model settings. @2008muyu/pi-plan lets you choose:

• Planning model — strong reasoning (e.g. claude-opus-4-6, gemini-3-pro, deepseek-r1)
• Execution model — lightweight for saving tokens (e.g. gpt-5.5, claude-sonnet-4)

Configure once via /plan-settings, then just /plan and go.

Install

pi install npm:@2008muyu/pi-plan

Or from GitHub:

pi install git:github.com/2008muyu/pi-plan

Restart pi (or run :reload).

Usage

/plan — Enter plan mode

/plan add authentication middleware with JWT support

Pi switches to your configured plan model, restricts tools to read-only (read/grep/find/ls), and the agent analyzes the codebase. Once ready, it calls submit_plan to create .plans/<name>/PLAN.md.

When the plan is done, you get a menu:

• Execute the plan — switches to the execution model, restores full tools
• Stay in plan mode — keep refining
• Refine the plan — edit the plan interactively

/plan resume — Resume a saved plan

/plan resume

Lists all in-progress plans from disk. Pick one to continue execution or re-enter planning.

/plan list — Show all plans

/plan list   # or /plan ls

Shows all saved plans with status and progress. Select one to resume, abandon, switch to, or delete.

/plan clean — Delete completed plans

/plan clean

Lists all done / superseded / abandoned plans for deletion. Select which to remove.

/plan abandon — Abandon current plan

/plan abandon

Marks the current plan as abandoned (without deleting its files).

/plan-settings — Unified settings

Opens an interactive menu for:

• Plan model provider + ID + thinking level
• Exec model provider + ID + thinking level
• Bash safety mode (blacklist / allowlist)
• Plan blocked tools (project-level, saved to .pi/pi-plan.json)

/todos — View progress

Shows all tasks with status icons.

| Icon | Status | |------|--------| | ○ | Pending | | ✓ | Done | | ⊘ | Skipped | | ✗ | Blocked | | ⏸ | Deferred (discovered) |

Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl+Alt+P | Toggle plan mode |

Configuration

Config stored in ~/.pi/agent/pi-plan.json. Also supports environment variables:

| Env variable | Default | Description | |-------------|---------|-------------| | PI_PLAN_PROVIDER | anthropic | Planning model provider | | PI_PLAN_MODEL | claude-opus-4-6 | Planning model ID | | PI_PLAN_THINKING | medium | Planning thinking level | | PI_EXEC_PROVIDER | openai | Execution model provider | | PI_EXEC_MODEL | gpt-5.5 | Execution model ID | | PI_EXEC_THINKING | low | Execution thinking level |

Tools

| Tool | Phase | Purpose | |------|-------|---------| | submit_plan | Plan | Submit finalized plan with tasks | | revise_plan | Plan | Revise an existing plan | | update_task | Exec | Mark task done/skipped/blocked | | update_tasks | Exec | Batch task update | | add_task | Exec | Capture discovered follow-up | | plan_status | Any | Read-only snapshot | | reconcile_plans | Any | Repair task/registry drift |

Plan Lifecycle

Plans have a lifecycle with automatic state transitions:

| State | Trigger | |-------|---------| | in-progress | Plan submitted via submit_plan | | done | All tasks completed (auto-detected) | | superseded | New plan started while another was in-progress (auto-detected) | | abandoned | User marks via /plan abandon, or prompted on exit if plan was never executed |

Tracked in .plans/plans.jsonl. Use /plan list to view, /plan clean to remove completed ones.

Project-Level Tool Blocking

In addition to the default blocked tools (edit/write, exec-only), you can block project-specific tools in plan mode:

// .pi/pi-plan.json
{ "planBlockedTools": ["godot_create_node", "godot_set_cell"] }

Configured via /plan-settings → option 6, or edit the file manually. This is project-scoped — different projects can have different blocked tools.

Blocked Task Handling

When a task is blocked during execution, a menu appears:

1. Skip — skip and continue
2. Provide instructions — give guidance, retry
3. Re-plan — go back to plan mode
4. Abort — exit plan mode

How it works

/plan → enterPlanMode()
  → save current model
  → switch to plan model
  → restrict to read-only tools
  → inject plan prompt

Agent analyzes → submit_plan
  → .plans/<name>/ files created

Execute → startExecution()
  → switch to exec model
  → restore full tools
  → inject execution prompt

Agent completes tasks → update_task
  → blocked? → menu → skip/instruct/re-plan/abort
  → done? → exit or stay

中文说明

简介

@2008muyu/pi-plan 是一个可配置的双阶段规划扩展。规划用强模型（思考深入），执行用轻模型（省 token），所有模型均可通过 /plan-settings 统一设置。

安装

pi install npm:@2008muyu/pi-plan

或从 GitHub 安装：

pi install git:github.com/2008muyu/pi-plan

重启 pi（或运行 :reload）。

使用方法

/plan — 进入规划模式

/plan 添加 JWT 认证中间件

pi 自动切换到配置的规划模型，工具限制为只读模式。Agent 分析代码后调用 submit_plan 提交方案。确认后可选择执行、继续规划或修改方案。

/plan resume — 恢复已保存的方案

显示磁盘上所有进行中的方案，选择继续执行或重新规划。

/plan-settings — 统一设置

交互菜单统一配置规划/执行模型的 provider、ID、思考强度，以及 bash 安全模式。

/todos — 查看进度

显示所有任务及其状态。

Blocked 任务处理

执行阶段如果任务被阻塞，弹菜单：跳过、提供说明重试、重新规划、终止执行。

配置

配置文件 ~/.pi/agent/pi-plan.json，也支持环境变量（见上方英文表格）。

许可证

MIT