@zenspc/pi-workflow

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

Packages

Package details

extension

Install @zenspc/pi-workflow from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@zenspc/pi-workflow
Package
@zenspc/pi-workflow
Version
0.1.0
Published
Jul 16, 2026
Downloads
82/mo · 82/wk
Author
ph03nix
License
MIT
Types
extension
Size
22.4 KB
Dependencies
0 dependencies · 5 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@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
  1. Choose execute when prompted.
  2. During execution, the agent marks steps complete with [DONE:n].
  3. 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