@mirakurunchan/pi-minimalplan

An OpenCode-style Plan/Build mode switch for Pi.

Pi starts in build mode with full tool access. /plan moves to a read-only mode: edit, write, and powershell leave the active tool set, while bash stays on and the plan prompt keeps it read-only, the same way OpenCode's plan agent behaves. There is no plan file and no todo pipeline. Just the switch.

Install

# from npm
pi install npm:@mirakurunchan/pi-minimalplan

# from a local checkout
pi install /absolute/path/to/pi-minimalplan

# try it for one run without installing
pi -e /absolute/path/to/pi-minimalplan

Then /reload inside Pi.

Usage

ctrl+tab toggles the mode while the editor has focus. It only fires in terminals that speak the Kitty keyboard protocol or modifyOtherKeys. Legacy terminals send plain tab, so use the commands below.

• /plan switches to plan mode
• /build switches to build mode
• /mode prints the current mode; /mode plan or /mode build sets it
• pi --plan starts a fresh session in plan mode

Tools the model can call:

• plan_enter switches from build to plan
• plan_exit switches from plan to build after a confirmation dialog

Behavior

• Plan mode saves the active tools on entry and restores them on exit. The mode tools change with the mode. Other per-session tool choices survive.
• The system rules apply read-only restrictions only in plan mode. Each run starts with a current-mode reminder. Mode tools send a new reminder before the next model request. Context filtering removes stale reminders.
• After you approve plan_exit, the model implements the approved plan in the same run. You do not need to send another prompt. User restrictions and unmet prerequisites still apply.
• The mode persists per session and follows the branch; it comes back on resume.
• A switch made while the model is responding is queued. It applies when the response finishes, so it never changes the in-flight turn. plan_exit and plan_enter apply at once, because the model asked for them.
• If you decline a solo plan_exit call, the turn ends without a follow-up response. Pi completes sibling tool calls first. Queued messages can cause another response.
• The footer shows ⏸ plan or ▶ build. A queued switch shows both, for example ▶ build → ⏸ plan.

Caveats

• If you use --tools, include both plan_enter and plan_exit so Pi can activate them.
• ctrl+tab needs the Kitty keyboard protocol or modifyOtherKeys. Legacy terminals send plain tab, which Pi uses for autocomplete. Fall back to /plan, /build, or /mode.
• tab and shift+tab stay as Pi's built-in keys: autocomplete accept and thinking-level cycle.
• Bash is not filtered in plan mode, same as OpenCode. The prompt tells the model to read and inspect; the hard guarantee is that edit and write are disabled.
• There is no plan file. After switching to build, ask the model to write the plan out.

Package layout

extensions/
  index.ts        wiring: keys, commands, tools, hooks, status, persistence
  modes.ts        pure tool-set logic
  prompts.ts      plan/transition reminder text
test/
  modes.test.mts       pure tool-set tests
  extension.test.mts   mode hooks and approval tests
  agent-loop.test.mts  scripted agent-loop regression tests
  harness.mts         shared extension test setup
  live-model.mts      optional RPC checks against a live model

Development

Requires Node >= 22.19.

npm ci --ignore-scripts   # install dev dependencies for typechecking
npm run typecheck         # tsc --noEmit
npm test                  # tool-set, extension, and agent-loop tests

To hack on a live copy, install the directory with pi install and run /reload after edits.

Live model checks

The optional checks need an installed Pi CLI and authentication for openai-codex/gpt-6.1-sol. They use temporary files outside this repository and send one prompt per case. The checks approve or decline the plan through RPC. They cover implementation after approval, declined approval, and an unmet prerequisite. They delete the temporary files after each case.

npm run test:model

PI_TEST_CLI selects another Pi executable. PI_TEST_MODEL selects another model. The regular npm test command does not make model requests.

Releases

CI publishes to npm. Merging to main creates a v<version> git tag and publishes that version, so every merge to main must bump the version in package.json. See RELEASING.md.

License

MIT