pi-plan-mode-tidy

Plan mode extension for Pi — a read-only exploration mode for safe code analysis.

Pair it with your own todo/execution workflow: this extension stops before execution by design.

What it does

When enabled, Pi is restricted to read-only exploration:

• Built-in edit and write tools are disabled — other active tools stay available
• Bash is allowlisted — destructive commands (rm, mv, redirects, package installs, sudo, state-changing git, pipes into interpreters, …) are blocked; only read-only commands (cat, ls, grep, git log|diff|show, …) run
• The agent is instructed to analyze the code, ask clarifying questions, and produce a numbered plan under a Plan: header instead of making changes

When the agent produces a plan, a prompt appears:

• Execute the plan (exit plan mode) — plan mode is switched off first, then the agent executes the plan with full tool access
• Stay in plan mode — keep exploring
• Refine the plan — type adjustments and the agent revises the plan (still read-only)

Install

pi install npm:pi-plan-mode-tidy

Or try it for one session without installing:

pi -e npm:pi-plan-mode-tidy

Pi loads the TypeScript sources directly (via jiti), no build step needed. Host packages (@earendil-works/pi-*) are peer dependencies and are supplied by Pi itself.

Usage

Plan format

Ask for analysis while in plan mode, and the agent responds with:

Some analysis...

Plan:
1. First step
2. Second step

Plan mode state is persisted in the session, so it survives pi --continue / --resume.

Safety guarantees

Plan mode is a read-only mode with no agent-escape path:

• Strict tool allowlist — only read, bash, grep, find, ls, questionnaire are active. All other tools (including any extension/MCP tool that might write) are deactivated, not merely filtered
• Bash allowlist — every piped/chained segment must be individually read-only; curl x | sh and similar injection pipes are blocked
• No self-bypass — the agent has no tool that can change its own toolset, edit files, or leave plan mode. Exiting requires a human action: /plan, Ctrl+Alt+P, or choosing Execute in the dialog
• Execution only outside plan mode — the Execute choice switches plan mode off (restores the saved toolset, clears the status) before the execution turn starts, so execution never runs under half-applied restrictions

Known ceiling: the bash allowlist is regex-based. It blocks destructive commands, redirects, and pipes into interpreters, but it is not a full shell sandbox (awk's system(), etc. can still do surprising things within those bounds). Treat it as a guardrail against accidental writes, not a security sandbox against a hostile agent.

Development

npm install          # fetch SDK types (dev only)
npm run check        # tsc --noEmit (strict)
npm test             # self-check on utils (plan extraction, safety allowlist)

Try a local checkout without publishing:

pi -ne --extension ./index.ts
# or install from a local path:
pi install ./pi-plan-mode-tidy

License

MIT