pi-plan

Plan mode for pi. Run /plan, the agent explores your codebase without being able to change it, writes a plan file, you review it, and then execution starts in a fresh session seeded with the plan.

Install

pi install npm:@burneikis/pi-plan

Try it without installing:

pi -e npm:@burneikis/pi-plan

Use

/plan add retry with backoff to the http client
/plan                 # reopen the review menu for the current plan

How it works

1. Plan. /plan <goal> puts the session in planning mode:

   • edit tools are disabled via setActiveTools()
   • write is allowed only for the plan file itself
   • bash is gated - anything that writes to disk, installs packages, mutates git, or shells out to an inline interpreter is blocked. This stops accidents, not a model that is deliberately trying to escape.
   • the agent writes the plan to ~/.pi/agent/plans/<session-id>/plan-<timestamp>.md

2. Review. Once the agent settles, you get a menu:

   Option	Effect
   Execute	Restores tools and starts a new session seeded with the plan
   Refine	You describe changes, the agent rewrites the plan, menu reopens
   Edit	You edit the plan text in pi's editor; rejected if it loses its steps
   Cancel	Deletes the plan file and returns to normal mode

3. Execute. The new session is named Plan: <title>, records the parent session, and starts with the plan as its first message. Old planning context is filtered out of the LLM context.

Plans are plain markdown on disk, so they survive restarts and can be reused or diffed.

Plan format

# Plan: <title>

## Goal
What changes and why.

## Steps

1. First step
2. Second step

## Notes
Constraints, open questions, decisions.

Steps are parsed from the ## Steps section only, numbered lines inside fenced code blocks are ignored, and the steps are renumbered sequentially so a mis-numbered plan still works.

Development

node --test utils.test.ts

All parsing and the bash gate live in utils.ts as pure functions, so they are covered by tests; index.ts only wires them to pi's API.