pi-plan-extension

Plan mode for the Pi coding agent: read-only exploration, structured plan files, and configurable models.

Install

From npm (after publish):

pi install npm:pi-plan-extension

From this repo (development):

./install.sh              # user settings (~/.pi/agent)
./install.sh --local      # project (.pi/settings.json)

Windows (PowerShell): \.\install.ps1 or \.\install.ps1 -Local

Verify: ./verify-install.sh or .\verify-install.ps1

Full cross-platform notes: docs/setup.md

Try without installing:

pi -e npm:pi-plan-extension
# or from a clone:
pi -e .

Usage

• /plan — toggle plan mode (read-only)
• --plan — start the session in plan mode

In plan mode the agent cannot use edit/write; bash is restricted to a read-only allowlist. When ready, the agent calls create_plan to write ./plans/<task-name>.md using a fixed template, or update_plan to refine sections.

After a plan is created or updated, you can Execute the plan (full tools, optional execute.model / execute.thinking), Stay in plan mode, or Exit. During execution, progress is tracked from Implementation Steps with [DONE:n] markers. Toggle with /plan or Ctrl+Alt+P.

Config

Merged (project overrides global):

1. ~/.pi/agent/pi-plan-extension.json
2. <cwd>/.pi/pi-plan-extension.json

{
  "allow_tools": ["web_search"],
  "plan": {
    "model": "anthropic/claude-sonnet-4-5",
    "thinking": "high"
  },
  "execute": {
    "model": "",
    "thinking": ""
  },
  "plans_dir": "plans",
  "bash_allowlist": true
}

Field	Description
allow_tools	Extra tool names to keep active in plan mode
plan.model	provider/model-id when entering plan mode (empty = unchanged)
plan.thinking	Thinking level in plan mode
execute.*	Used when execute flow is enabled (later phase)
plans_dir	Directory for plan files (relative to cwd)
bash_allowlist	Block destructive bash commands in plan mode

Plan template

Plans are written to plans/<task-name>.md with sections: Overview, Goals, Context / Findings, Approach, Implementation Steps, Files to Modify, Risks / Edge Cases, Testing, Acceptance Criteria.

Publish (maintainers)

./publish.sh --dry-run   # tests + npm pack dry-run
./publish.sh --yes       # publish public to npm

Windows:

.\publish.ps1 -DryRun
.\publish.ps1 -Yes

Requires npm login. Package: pi-plan-extension@0.1.0 (--access public).

License

MIT