pi-plan-mode — Codex-like plan mode for Pi

@signalridge/pi-plan-mode adds a Codex-like /plan collaboration mode to Pi. Plan mode is for read-only exploration, clarifying questions, and a structured implementation-ready plan before any code mutation happens.

Pi core intentionally does not ship a built-in plan mode; this package provides one as an independently installable extension.

Read-only risk reduction, not a sandbox. Mutating built-ins and unsafe shell forms are blocked. Custom/extension tools are disabled by default; enabling one trusts its whole effective implementation. An enabled Agent grants the child's own tool policy, not read-only enforcement. Tests/builds may write caches or execute trusted project hooks; Git/gh inspection can disclose secrets.

Install

The current tested host is Pi 1.0.4. Host-provided dependencies use "*" peers to identify module ownership, not to guarantee compatibility with every Pi version. See the compatibility guide for verification details.

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

Try without installing permanently:

pi -e npm:@signalridge/pi-plan-mode

Try this package locally from the repository root:

pi -e ./packages/pi-plan-mode

Usage

/plan design the migration
/plan finalize
/plan show
/plan implement
# Or save/export instead:
/plan save
/plan export PLAN.md

Explore → ask material decisions with plan_mode_question → finish with standalone plan_mode_complete({ plan }) → review. Implement here keeps the conversation; Start fresh and implement transfers only the approved plan to a linked session (normal destination project resources still load). Saved plans are session-local, outside ordinary context, and never silently overwritten.

Tools and Settings are locked during Planning/ready state; configure before activation. Required Plan tools remain available, but no late tools enter an active workflow. Completion rejects blank or >50,000-JavaScript-character plans and is model-only; legacy standalone <proposed_plan> blocks remain supported. A turn without completion stays active; use finalize to recover.

Export is explicit user-requested mutation, never a model-write escape: default PLAN.md, relative to current cwd, absolute or leading @ accepted, missing parents created. Existing files/directories/symlinks are never overwritten. Markdown is exact except one trailing newline. Failed/cancelled exports preserve state; saved/active exports do not exit.

Print/JSON support direct activation, export/save/clear, not tool selectors, show or implementation. Fresh handoff failures leave source recovery available; model/auth drift never silently submits to a different destination. Complete workflow, editor fallback, provenance and branch recovery.

Settings

Optional $PI_CODING_AGENT_DIR/pi-plan-mode.json (normally ~/.pi/agent/pi-plan-mode.json); read at session start, created only on explicit save. Inactive-menu Settings edits future workflows.

Safe shell defaults: git status/log/diff/show/branch/remote/ls-files/grep. Explicit opt-ins: rev-parse/blame/describe/merge-base/ls-tree/cat-file and gh pr view/list, issue view/list (JSON output required). One direct argv-style inspection command only; no shell lists, pipes, substitutions, redirects, expansion, background jobs, installs or mutating flags. Use git --no-optional-locks status and git diff --no-ext-diff --no-textconv to suppress helpers. Accepted/rejected examples and validators.

The reference JSON is an example, not omission defaults: its shortcut and shell opt-ins require explicit choice. Saves preserve unknown fields and fail closed on invalid files; legacy plan-mode.json remains readable with warning. Retention is captured at handoff: keep reinjects the exact plan after compaction, clear-on-start keeps only the first request, clear-after-first-run waits through retries/queued continuation to settlement. Model switching applies only to Implement here, never fresh implementation or the configured default; manual/ambiguous selections are not forced back. Full settings/model/retention contract.

Statuses: plan active / ready / saved / implementing. The entrypoint forwards to internal plan-mode modules.

License

MIT. See LICENSE.

Reference

Detailed contracts and legacy section links:

• Default Plan tools
• After Implement
• Implementation model
• Export destination
• Safe shell subcommands
• Thinking level