pi-openplan

Plan mode extension for pi — read-only exploration, structured planning, and phased execution tracking.

Toggle into plan mode to safely explore codebases, research approaches, write structured plans, and execute them phase by phase with progress tracking.

Features

Feature	Description
Read-only mode	Blocks edit/write tools and destructive bash commands via dual-gate safety
Structured plans	Save plans to .pi/plans/ with YAML frontmatter (title, status, type, dates). Renders inline in conversation on save.
Plan management	LLM tools: plan_write, plan_read, plan_list with status filtering
Interactive Q&A	plan_question tool — TUI overlay with options, multi-select, and free-text answers
Progress tracking	Mark steps complete with [DONE:n] tags — widget shows live progress. Survives restarts.
Pause points	⏸️ PAUSE markers create verification gates. Auto-pauses execution at each gate.
State persistence	Plan mode, todos, and execution mode survive session restarts and /reload

Installation

pi install npm:pi-openplan          # from npm
pi install git:github.com/wilfredinni/pi-openplan  # from git
pi -e ./path/to/pi-openplan         # try without installing

After installing, restart pi or run /reload.

Quick Start

/plan                 # enable plan mode (read-only)
/plans                # list saved plans
/execute_plan <name>  # execute a saved plan
/plan                 # disable plan mode (full access restored)

Commands

/plan

Toggle plan mode. When enabled, tools are restricted to read-only and bash commands go through the dual-gate safety check (see Bash Safety).

/plans

List all saved plans from .pi/plans/ with filename, status, title, and creation date.

/execute_plan [plan-name]

Exit plan mode and execute a saved plan. Loads the plan, extracts phases, and sets status to in_progress. If the plan is not found, execution is aborted and plan mode is restored. Run without a name to enter generic execution mode.

Keyboard Shortcuts

Shortcut	Action
Ctrl+Alt+P	Toggle plan mode

CLI Flags

pi --plan    # start pi in plan mode

LLM Tools

These tools are registered for the agent to call during plan mode:

plan_write — Save a plan. Accepts filename, title, content (markdown), and optional type (feature, fix, refactor, chore).

plan_read — Read a saved plan by filename (fuzzy match). Use full: false for metadata only.

plan_list — List all plans, optionally filtered by status (draft, approved, in_progress, done).

plan_question — Present clarifying questions with options. Supports single-select, multi-select, and custom free-text. Max 4 questions, 2–4 options each. Falls back to text in non-interactive mode.

Bash Safety

Plan mode uses a dual-gate system to block destructive commands:

1. Destructive gate — blocks 32 patterns (rm, mv, git push, npm install, sudo, curl -d, curl -o, wget -O, pipe-to-interpreter, etc.)
2. Safe gate — only allows 48 known-safe patterns (cat, grep, ls, git status, git log, npm list, curl (read-only), wget -O -, etc.)

A command must pass both gates. Unknown commands are conservatively blocked.

Plan File Format

Plans are markdown files in .pi/plans/ with YAML frontmatter:

---
title: "Feature Name"
status: draft
created: "2026-01-15T12:00:00Z"
type: feature
---

# Feature Name Implementation Plan

## Overview
...

Statuses: draft, approved, in_progress, done Types: feature, fix, refactor, chore

Progress Tracking

During execution, include [DONE:n] in responses where n matches the phase number. The widget updates automatically. On session resume, completed markers are re-scanned to restore state.

Pause Points

Include ⏸️ PAUSE or PAUSE in your plan to create verification gates. The extension pauses and asks for confirmation before continuing.

Plan Mode Workflow

1. Toggle on — /plan or Ctrl+Alt+P
2. Explore — read files, search code, research approaches (read-only)
3. Ask — use plan_question to clarify scope, constraints, priorities
4. Plan — agent creates a structured plan via plan_write with phases, verification, risks
5. Review — agent presents plan summary and stops
6. Execute — /execute_plan <plan-name> loads plan, begins phased execution
7. Track — use [DONE:n] to mark steps complete
8. Verify — review at each ⏸️ PAUSE gate before continuing
9. Complete — all steps done; extension announces completion, resets execution mode

Development

npm install            # install dev deps (typecheck/lint/test only)
npm run typecheck      # tsc --noEmit
npm run lint           # biome check .
npm run lint:fix       # biome check --write .
npm test               # vitest — 204 tests, 10 files
npm run test:coverage  # vitest with v8 coverage
pi -e .                # load extension locally

See AGENTS.md for architecture, release process, and gotchas.

Requirements

• pi 0.74.0 or later
• Node.js 22+

License

MIT