pi-plan

A pi coding agent extension that adds a review-plan tool — lets the agent write a named markdown plan to disk and present it in an interactive terminal widget for the user to approve, request changes, or ask a question before execution begins.

Install

pi install npm:@piotr-oles/pi-plan

Usage

The extension registers a review-plan tool. The intended workflow is:

1. The agent writes the plan file using the built-in write tool (path under ~/.pi/plan/<repo>/<name>.md)
2. The agent calls review-plan with the relative path

Instruct the agent to follow this pattern:

Write the plan file to ~/.pi/plan/<repo>/<name>.md first, then call review-plan with the relative path.

Or reference it in a prompt template / skill file to enforce it project-wide.

How it works

When the agent calls review-plan:

1. Ensures ~/.pi/plan/ is a git repository (initialises it on first use)

2. Commits the plan file with message create: <name>.md

3. Hides the working indicator and shows an interactive widget with three options:

   • Request changes — edit the file then select this; the agent gets a diff of your edits and is told to update the plan, then call review-plan again
   • Approve — edit the file (optionally) then select this; the agent gets a diff of any edits and is told to proceed with execution
   • Ask question — type a free-form question; the agent receives it and can reply before you decide

4. After the user responds, any edits made to the file before selecting are committed (approve: <name>.md / request-changes: <name>.md) and a diff is computed and sent back to the agent

Widget responses

Selection	Agent receives
Approve (no edits)	approve result, empty diff — told to proceed
Approve (with edits)	approve result + git diff — told to address comments, fix up plan, then proceed
Request changes (with edits)	request-changes result + git diff — told to address comments, update plan, call review-plan again
Request changes (no edits)	request-changes result, empty diff — told to ask the user what to change
Ask question	question result with the question text
Esc / cancel	cancel result

Git history

All plan versions are tracked in a git repo at ~/.pi/plan/. Each interaction creates a commit:

• create: <name>.md — initial write by the agent
• approve: <name>.md — user approved (records any edits made before approving)
• request-changes: <name>.md — user requested changes (records edits)

Development

pnpm install
pnpm test
pnpm typecheck
pnpm check

To test changes manually, pass the source entry point directly to pi:

pi -ne -e packages/pi-plan/src/index.ts