> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Plannotator with Pi

> Install and update the Plannotator Pi extension, review plans without making the agent wait, and use code review, document annotation, and last-message review.

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

```bash theme={null}
pi install npm:@plannotator/pi-extension
```

Pi 0.79.1 or later is required.

## Enter plan mode

Start Pi in plan mode:

```bash theme={null}
pi --plan
```

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](/open-source/workflows/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.

```json theme={null}
{
  "executionMode": "external"
}
```

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:

```ts theme={null}
{
  cwd: string;
  planFilePath: string;
  planContent: string;
  feedback?: string;
}
```

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

```text theme={null}
/plannotator-review
/plannotator-annotate path/to/spec.md
/plannotator-last
```

`/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

```bash theme={null}
pi -e npm:@plannotator/pi-extension
```

## Update

If you also use the standard Plannotator installer, rerunning it updates the extension when `pi` is on your `PATH`. Otherwise, update from Pi:

```bash theme={null}
pi update --extensions
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.