Skip to main content
Pi uses its own Plannotator extension. You do not need the standard Plannotator installer for this setup. The extension provides Pi’s plan tool and slash commands; it does not install Plannotator’s standalone core or extra Agent Skills.

​
Install

Pi 0.79.1 or later is required.

​
Enter plan mode

Start Pi in plan mode:
You can also run /plannotator-plan-mode or press Ctrl+Alt+P during a session. Both toggle plan mode. In plan mode, the agent writes a Markdown plan and calls plannotator_submit_plan. Plannotator opens the plan for approval or annotated feedback. After approval, Pi enters execution mode and tracks checklist progress.

​
Plan review does not make the agent wait

Since Plannotator 0.28.0, the agent does not wait while you review. When the review opens, the agent ends its turn. Your decision arrives later as a message.
  • You can keep chatting with the agent while the review is open.
  • The agent still cannot change code. Planning restrictions stay on until you approve.
  • If the agent revises the plan while the review is open, the open tab updates to the new version and keeps your comments.
  • Pressing Esc in Pi no longer cancels an open plan review. To abandon a review, leave plan mode with /plannotator-plan-mode or Ctrl+Alt+P. Leaving plan mode closes the open review.

​
Ask this session

In plan review, code review, annotate, and /plannotator-last, Ask AI is answered by your Pi session. It is the only Ask AI option there, so there is no provider picker. Your question shows in Pi’s chat. If the agent is busy, choose Ask when it finishes or Interrupt and ask now. In remote mode, you pick a separate provider instead. See Ask this session.

​
Hand an approved plan to another extension

Pi uses automatic in-session execution by default. Set executionMode in the global or project config:
  1. ~/.pi/agent/plannotator.json
  2. <project>/.pi/plannotator.json
The project config overrides the global config.
After approval, external mode completes these actions in order:
  1. Restores the model, thinking level, and active tools from before planning.
  2. Returns Plannotator to idle.
  3. Emits plannotator:plan-approved with this payload:
A companion extension can listen to that Pi event and own execution. Plannotator does not enter its executing phase or track checklist progress in external mode. Tools from other extensions remain available. Plannotator disables only the tools that it enabled.

​
Manual commands

/plannotator-review uses the detected Git, GitButler, or Jujutsu provider. Pass --git or --gitbutler to force one. GitButler review requires but 0.21.0 or later on PATH.

​
Try without installing

​
Update

If you also use the standard Plannotator installer, rerunning it updates the extension when pi is on your PATH. Otherwise, update from Pi:
This updates your installed Pi packages, Plannotator included. A plain pi update updates only Pi itself. To update only Plannotator, run pi update npm:@plannotator/pi-extension. Restart Pi after updating. Last verified against Plannotator OSS v0.25.1 on July 31, 2026. The plan review, Ask this session, and update sections were checked against Plannotator v0.28.0 on October 4, 2026. Maintained by the Plannotator project.
Last modified on October 5, 2026