@skibum1869/pi-plan-mode

Read-only plan mode for the pi coding agent: exploration, numbered plan extraction, and tracked [DONE:n] execution.

While plan mode is active, edit and write tools are disabled and bash is restricted to an allowlist of read-only commands — enforced by a tool_call gate, not prompt discipline.

Install

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

Or try it without installing:

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

Toggle

| Toggle | What | |--------|------| | /plan | Toggle plan mode | | Ctrl+Tab | Toggle plan ↔ build mode | | Ctrl+Alt+P | Toggle plan mode | | --plan | Start pi directly in plan mode | | /todos | Show current plan progress |

Workflow

1. Toggle plan mode on — the footer shows ⏸ plan.
2. Ask the agent to explore and design. It produces a numbered plan under a Plan: header.
3. Pick Execute the plan (tracked execution with [DONE:n] progress, footer shows 📋 n/m), Stay in plan mode, or Refine the plan.
4. During execution each completed step is marked with [DONE:n]; when all steps finish the widget clears and full access resumes.

How it works

• Tool gate: plan mode swaps the active tool set to read-only tools (read, bash, grep, find, ls) and hides edit/write.
• Bash allowlist: safe read-only commands (cat, grep, find, ls, git status/log/diff, …) pass; mutating commands (rm, mv, redirects, git commit/push, installs, editors, …) are blocked with a message telling the agent to propose a plan instead. Compound commands must match the allowlist as a whole.
• Session persistence: plan state, todo list, and execution progress survive /resume.
• Footer status: ⏸ plan (planning) / 🔨 build (normal) / 📋 n/m (executing).

Security

Pi extensions run with your user permissions. Plan mode is a guardrail, not an operating-system sandbox — its allowlist blocks common mutation patterns but cannot prove arbitrary shell commands are read-only.

License

MIT — derived from the plan-mode example in @earendil-works/pi-coding-agent.