@milanglacier/pi-plan-mode

Structured planning mode for pi — think before you code.

Fork notice

This repository is a standalone fork of @ifi/pi-plan, originally created by Ifiok Jr.. The initial source was imported from ifiokjr/oh-pi@7ef2e7b.

The original project remains the canonical upstream. Its copyright and MIT license terms continue to apply.

Why use this?

Direct implementation works for small tasks, but complex features benefit from planning first:

• Avoid rework: Plan the architecture before writing code
• Capture decisions: The plan file documents why you made certain choices
• Resume later: Planning state persists across sessions

Plan mode turns planning into a first-class pi workflow with its own tools, banners, and file management.

What planning feels like

/plan

┌─ Start Plan Mode ──────────────────────────┐
│                                             │
│  Empty branch    Start a new planning       │
│                  branch from scratch        │
│                                             │
│  Current branch  Continue from where the    │
│                  conversation left off      │
│                                             │
└─────────────────────────────────────────────┘

While active, a banner stays visible:

┌ PLAN MODE ─ /home/user/projects/app/session-abc.plan.md ─────┐
│ [plan-mode tools are active: request_user_input, set_plan]     │
└───────────────────────────────────────────────────────────────┘

Exiting plan mode shows a summary:

Plan mode ended.
Plan saved to: /home/user/projects/app/session-abc.plan.md

Installation

pi install npm:@milanglacier/pi-plan-mode

Commands

Command	Action
/plan	Enter plan mode (or show actions if already active)
/plan [file-path]	Use a specific file as the plan file
/plan [directory]	Create a timestamped plan file in that directory

Shortcut

Alt+P — toggle plan mode without typing /plan.

Tools available in plan mode

Only while plan mode is active, these tools are exposed:

Tool	Purpose
request_user_input	Ask you clarifying questions with optional choices
set_plan	Overwrite the plan file with the latest full plan text

When plan mode ends, these tools disappear.

Customization

The default plan-mode prompt lives at prompts/PLAN.prompt.md. Override it globally by creating ~/.pi/agent/PLAN.prompt.md. If the override file is missing or blank, the bundled prompt is used.

Plan file management

• Default plan file: replaces the session extension with .plan.md in the session directory
• Plan files persist after exiting — resume later with /plan
• While active, /plan <location> moves the current plan file

Notes

• Ships raw TypeScript — no build step needed
• Plan mode does not automatically trigger implementation — it's for thinking, not coding