@zenspc/pi-workflow

Plan mode for read-only exploration and tracked plan execution in Pi.

Install

pi install npm:@zenspc/pi-workflow

Local development:

pi -e ./packages/pi-workflow
pi install ./packages/pi-workflow

Features

• Built-in write tools disabled while planning
• Bash restricted to allowlisted read-only commands
• Extracts numbered steps from Plan: sections
• Progress tracking widget during execution
• [DONE:n] markers for step completion
• Session persistence across resume

Commands

• /plan - toggle plan mode
• /todos - show current plan progress
• Ctrl+Alt+P - toggle plan mode
• --plan - start Pi already in plan mode

Usage

1. Enable plan mode with /plan or --plan.
2. Ask the agent to analyze code and create a plan.
3. Prefer a numbered plan under a Plan: header:

Plan:
1. First step description
2. Second step description
3. Third step description

4. Choose execute when prompted.
5. During execution, the agent marks steps complete with [DONE:n].
6. The progress widget shows completion status.

How it works

Plan mode

• Built-in edit / write tools disabled
• Other active tools remain available
• Bash filtered through a read-only allowlist
• Agent explores and drafts a plan without mutating files

Execution mode

• Full tool access restored
• Agent executes steps in order
• [DONE:n] markers track completion
• Widget shows progress

Command allowlist

Safe examples:

• File inspection: cat, head, tail, less, more
• Search: grep, find, rg, fd
• Directory: ls, pwd, tree
• Git read: git status, git log, git diff, git branch
• Package info: npm list, npm outdated, yarn info
• System info: uname, whoami, date, uptime

Blocked examples:

• File modification: rm, mv, cp, mkdir, touch
• Git write: git add, git commit, git push
• Package install: npm install, yarn add, pip install
• System: sudo, kill, reboot
• Editors: vim, nano, code

Security note

Plan mode is a workflow aid. While planning, built-in write tools are disabled and bash is filtered through a read-only allowlist. That is not a hard security boundary against a malicious or confused model if other tools remain available, if plan mode is turned off, or if allowlist gaps exist. Do not treat plan mode as a sandbox.

Source

extensions/plan-mode/index.ts
extensions/plan-mode/utils.ts