@kmiyh/pi-plan-mode

Pi extension that adds a read-only plan mode for safe code analysis, plan extraction, and execution progress tracking.

Packages

Package details

extension

Install @kmiyh/pi-plan-mode from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@kmiyh/pi-plan-mode
Package
@kmiyh/pi-plan-mode
Version
2.0.0
Published
May 8, 2026
Downloads
173/mo · 12/wk
Author
kmiyh
License
MIT
Types
extension
Size
19.2 KB
Dependencies
0 dependencies · 4 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

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

README

@kmiyh/pi-plan-mode

@kmiyh/pi-plan-mode is a Pi extension that adds a read-only exploration mode for safe code analysis, planning, and tracked execution.

It is packaged from Pi's examples/extensions/plan-mode extension.

Features

  • Read-only tools: restricts available tools to read, bash, grep, find, ls, and questionnaire
  • Bash allowlist: only read-only bash commands are allowed while plan mode is enabled
  • Plan extraction: extracts numbered steps from Plan: sections
  • Progress tracking: shows a widget with completion status during execution
  • [DONE:n] markers: tracks explicit step completion tags from assistant responses
  • Session persistence: state survives session resume and reloads

Installation

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

Or install directly from GitHub:

pi install git:github.com/Kmiyh/pi-plan-mode

Commands

  • /plan - toggle plan mode
  • /todos - show current plan progress
  • Ctrl+Alt+P - toggle plan mode shortcut

Usage

  1. Enable plan mode with /plan or start Pi with --plan.
  2. Ask the agent to analyze code and create a plan.
  3. The agent should output a numbered plan under a Plan: header:
Plan:
1. First step description
2. Second step description
3. Third step description
  1. Choose Execute the plan when prompted.
  2. During execution, the agent marks steps complete with [DONE:n] tags.
  3. The progress widget shows completion status.

How it works

Plan mode (read-only)

  • Only read-only tools are available.
  • Bash commands are filtered through an allowlist.
  • The agent creates a plan without making changes.

Execution mode

  • Full tool access is restored.
  • The agent executes steps in order.
  • [DONE:n] markers track completion.
  • A widget shows progress.

Command allowlist

Safe commands include:

  • file inspection: cat, head, tail, less, more
  • search: grep, find, rg, fd
  • directory: ls, pwd, tree
  • Git read-only commands: git status, git log, git diff, git branch
  • package info: npm list, npm outdated, yarn info
  • system info: uname, whoami, date, uptime

Blocked commands include:

  • file modification: rm, mv, cp, mkdir, touch
  • Git write commands: git add, git commit, git push
  • package installs: npm install, yarn add, pip install
  • system commands: sudo, kill, reboot
  • editors: vim, nano, code

Local development

npm install
npm run typecheck
pi -e ./src/index.ts

License

MIT