--- title: "@henryqw/pi-advisor" seo: description: "Opt-in second-model review of each Pi agent run after it settles, with graded notes and one blocker follow-up." ---
Version v0.1.1
Monthly npm downloadsMIT license
Let a second model examine the tool calls and results of each agent run after Pi settles the run. The advisor returns graded notes. A blocker sends one follow-up message that makes the agent fix it. ## Install ```bash pi install npm:@henryqw/pi-advisor ``` The advisor uses the `pi-advisor/review` Model Task. Its default Task Profile is `balanced`. Run `/task-models` to configure a route for that profile before you turn the advisor on. ## Works with | Package | Relationship | Purpose | | --- | --- | --- | | [`@henryqw/pi-goal`](https://pi.henry.wang/extensions/pi-goal) | Improves | Goal continuations stay in one run. The advisor examines all of that work after the run settles. | | [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) | Required | Provides the advisor model route. | ## Use Run `/advisor on`. Then send a prompt that makes the agent use tools. When the run settles, the advisor examines it in the background, and Pi shows the result. | Surface | Type | Purpose | | --- | --- | --- | | `/advisor on` | command | Turn the advisor on for this conversation branch. | | `/advisor off` | command | Turn the advisor off for this conversation branch. | | `/advisor status` | command | Show whether the advisor is on for this conversation branch. | | `Advisor reviewing…` | ui | Footer status while the review runs. | The advisor is off by default. ### Results | Reply | What Pi shows | Continuation | | --- | --- | --- | | `PASS` | The `Advisor: PASS` notice. | No | | Only `nit` notes | One notice with all notes. | No | | A `concern` note | One warning with all notes. | No | | A `blocker` note | One warning with all notes. | One follow-up for each user prompt | | Malformed reply, or a reply longer than 8,000 characters | One warning, one time in each session. | No | ## Flow ![Pi Advisor flow: after the run settles, review gates decide whether the advisor runs; a PASS or notes reply ends the review, and a blocker sends one follow-up message that starts a new turn](data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMjgwIiBoZWlnaHQ9IjcyMCIgdmlld0JveD0iMCAwIDEyODAgNzIwIiByb2xlPSJpbWciIGFyaWEtbGFiZWxsZWRieT0iYWR2aXNvci1mbG93LXRpdGxlIGFkdmlzb3ItZmxvdy1kZXNjIiBpZD0iYWR2aXNvci1mbG93LXJvb3QiPgo8dGl0bGUgaWQ9ImFkdmlzb3ItZmxvdy10aXRsZSI+UGkgQWR2aXNvciByZXZpZXcgZmxvdzwvdGl0bGU+CjxkZXNjIGlkPSJhZHZpc29yLWZsb3ctZGVzYyI+QWZ0ZXIgYW4gYWdlbnQgcnVuIHNldHRsZXMsIHJldmlldyBnYXRlcyBkZWNpZGUgd2hldGhlciB0aGUgYWR2aXNvciBydW5zLiBJZiBhbGwgZ2F0ZXMgcGFzcywgb25lIHRvb2wtZnJlZSBNb2RlbCBUYXNrIHJlcXVlc3QgcnVucyBpbiB0aGUgYmFja2dyb3VuZCBhbmQgcmV0dXJucyBhIHJlcGx5LiBQQVNTLCBuaXQsIGNvbmNlcm4sIG1hbGZvcm1lZCwgdGltZW91dCwgZXJyb3IsIGNhbmNlbGxlZCwgb3Igc3RhbGUgcmVwbGllcyBlbmQgdGhlIHJldmlldyBhbmQgUGkgc3RheXMgaWRsZS4gQSBibG9ja2VyIHNlbmRzIGEgdmlzaWJsZSBwaS1hZHZpc29yLWJsb2NrZXIgZm9sbG93LXVwIG1lc3NhZ2UgdGhhdCBzdGFydHMgb25lIG5ldyBydW4gZm9yIGVhY2ggdXNlciBwcm9tcHQuPC9kZXNjPgo8ZGVmcz4KICAgICAgPHN0eWxlPkBpbXBvcnQgdXJsKCdodHRwczovL2ZvbnRzLmdvb2dsZWFwaXMuY29tL2NzczI/ZmFtaWx5PUluc3RydW1lbnQrU2VyaWY6aXRhbEAwOzEmYW1wO2ZhbWlseT1HZWlzdDp3Z2h0QDQwMDs1MDA7NjAwJmFtcDtmYW1pbHk9R2Vpc3QrTW9ubzp3Z2h0QDQwMDs1MDA7NjAwJmFtcDtkaXNwbGF5PXN3YXAnKTsKICAgICAgI2Fkdmlzb3ItZmxvdy1yb290IHsgY29sb3I6ICMxMDE4Mjg7IH08L3N0eWxlPgo8bWFya2VyIGlkPSJhZHZpc29yLWZsb3ctYXJyb3ciIHZpZXdCb3g9IjAgMCA4IDgiIHJlZlg9IjciIHJlZlk9IjQiIG1hcmtlcldpZHRoPSI4IiBtYXJrZXJIZWlnaHQ9IjgiIG9yaWVudD0iYXV0byI+PHBhdGggZD0iTTAgMCBMOCA0IEwwIDhaIiBmaWxsPSIjNGM1NjY1Ii8+PC9tYXJrZXI+CjxtYXJrZXIgaWQ9ImFkdmlzb3ItZmxvdy1hcnJvdy1ibHVlIiB2aWV3Qm94PSIwIDAgOCA4IiByZWZYPSI3IiByZWZZPSI0IiBtYXJrZXJXaWR0aD0iOCIgbWFya2VySGVpZ2h0PSI4IiBvcmllbnQ9ImF1dG8iPjxwYXRoIGQ9Ik0wIDAgTDggNCBMMCA4WiIgZmlsbD0iIzFkNGVkOCIvPjwvbWFya2VyPgo8L2RlZnM+CjxyZWN0IHdpZHRoPSIxMjgwIiBoZWlnaHQ9IjcyMCIgZmlsbD0iI2YwZWVlOSIvPgo8dGV4dCB4PSI0MCIgeT0iNTIiIGZvbnQtZmFtaWx5PSJJbnN0cnVtZW50IFNlcmlmLCBzZXJpZiIgZm9udC1zaXplPSIyOCIgZmlsbD0iIzEwMTgyOCI+QW4gYWR2aXNvciByZXZpZXcgYWZ0ZXIgdGhlIHJ1biBzZXR0bGVzPC90ZXh0Pgo8IS0tIENvbm5lY3Rpb25zIHByZWNlZGUgbm9kZXMuIEVhY2ggcGF0aCBoYXMgaXRzIG93biBhdHRhY2htZW50IHBvaW50LiAtLT4KPGcgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjNGM1NjY1IiBzdHJva2Utd2lkdGg9IjEuMiIgbWFya2VyLWVuZD0idXJsKCNhZHZpc29yLWZsb3ctYXJyb3cpIj4KPHBhdGggZD0iTTI0MCAxNjggSDMyMCIvPgo8cGF0aCBkPSJNNjAwIDE2OCBINjgwIi8+CjxwYXRoIGQ9Ik05MDAgMTY4IEg5ODAiLz4KPHBhdGggZD0iTTQ2MCAyOTYgVjMzNiIvPgo8cGF0aCBkPSJNMTAwMCAyOTYgVjM4NCBINjAwIi8+CjwvZz4KPGcgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMWQ0ZWQ4IiBzdHJva2Utd2lkdGg9IjEuNiIgbWFya2VyLWVuZD0idXJsKCNhZHZpc29yLWZsb3ctYXJyb3ctYmx1ZSkiPgo8cGF0aCBkPSJNMTE4MCAyOTYgVjUyOCBIOTAwIi8+CjxwYXRoIGQ9Ik02ODAgNTI4IEgxNDggUTE0MCA1MjggMTQwIDUyMCBWMjE2Ii8+CjwvZz4KPCEtLSBMYWJlbCBtYXNrcyBzdGF5IGNsZWFyIG9mIHRoZWlyIGNvbm5lY3RvcnMgYW5kIGFsbCBub2RlIHJlY3RhbmdsZXMuIC0tPgo8ZyBmaWxsPSIjZjBlZWU5Ij4KPHJlY3QgeD0iNjEyIiB5PSIxNDgiIHdpZHRoPSI1NiIgaGVpZ2h0PSIxMiIvPgo8cmVjdCB4PSIyNDQiIHk9IjE0OCIgd2lkdGg9IjcyIiBoZWlnaHQ9IjEyIi8+CjxyZWN0IHg9IjQ2NCIgeT0iMzA2IiB3aWR0aD0iNzIiIGhlaWdodD0iMTIiLz4KPHJlY3QgeD0iNzQ2IiB5PSIzNjQiIHdpZHRoPSIxMDgiIGhlaWdodD0iMTIiLz4KPHJlY3QgeD0iMTE4NCIgeT0iNDA2IiB3aWR0aD0iNDQiIGhlaWdodD0iMTIiLz4KPHJlY3QgeD0iNDIwIiB5PSI1MDgiIHdpZHRoPSI4MCIgaGVpZ2h0PSIxMiIvPgo8L2c+CjxnIGZvbnQtZmFtaWx5PSJHZWlzdCBNb25vLCBtb25vc3BhY2UiIGZvbnQtc2l6ZT0iOCIgZmlsbD0iIzRjNTY2NSI+Cjx0ZXh0IHg9IjY0MCIgeT0iMTU3IiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj5BTEwgUEFTUzwvdGV4dD4KPHRleHQgeD0iMjgwIiB5PSIxNTciIHRleHQtYW5jaG9yPSJtaWRkbGUiPkFHRU5UX1NFVFRMRUQ8L3RleHQ+Cjx0ZXh0IHg9IjQ2OCIgeT0iMzE1Ij5BTlkgR0FURSBGQUlMUzwvdGV4dD4KPHRleHQgeD0iODAwIiB5PSIzNzMiIHRleHQtYW5jaG9yPSJtaWRkbGUiPk5PIEJMT0NLRVIsIE9SIENBUFBFRDwvdGV4dD4KPHRleHQgeD0iMTE4OCIgeT0iNDE1IiBmaWxsPSIjMWQ0ZWQ4Ij5CTE9DS0VSPC90ZXh0Pgo8dGV4dCB4PSI0NjAiIHk9IjUxNyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzFkNGVkOCI+TkVXIFJVTjwvdGV4dD4KPC9nPgo8cmVjdCB4PSI0MCIgeT0iMTIwIiB3aWR0aD0iMjAwIiBoZWlnaHQ9Ijk2IiByeD0iOCIgZmlsbD0iI2ZmZmZmZiIgc3Ryb2tlPSIjMTAxODI4IiBzdHJva2Utb3BhY2l0eT0iMC4yIi8+CjxyZWN0IHg9IjMyMCIgeT0iOTYiIHdpZHRoPSIyODAiIGhlaWdodD0iMjAwIiByeD0iOCIgZmlsbD0iI2U2ZTRkZSIgc3Ryb2tlPSIjMTAxODI4IiBzdHJva2Utb3BhY2l0eT0iMC4yIi8+CjxyZWN0IHg9IjY4MCIgeT0iMTIwIiB3aWR0aD0iMjIwIiBoZWlnaHQ9Ijk2IiByeD0iOCIgZmlsbD0iI2ZmZmZmZiIgc3Ryb2tlPSIjMTAxODI4IiBzdHJva2Utb3BhY2l0eT0iMC4yIi8+CjxyZWN0IHg9Ijk4MCIgeT0iOTYiIHdpZHRoPSIyNjAiIGhlaWdodD0iMjAwIiByeD0iOCIgZmlsbD0iI2U2ZTRkZSIgc3Ryb2tlPSIjMTAxODI4IiBzdHJva2Utb3BhY2l0eT0iMC4yIi8+CjxyZWN0IHg9IjMyMCIgeT0iMzM2IiB3aWR0aD0iMjgwIiBoZWlnaHQ9Ijk2IiByeD0iOCIgZmlsbD0iI2ZmZmZmZiIgc3Ryb2tlPSIjMTAxODI4IiBzdHJva2Utb3BhY2l0eT0iMC4yIi8+CjxyZWN0IHg9IjY4MCIgeT0iNDgwIiB3aWR0aD0iMjIwIiBoZWlnaHQ9Ijk2IiByeD0iOCIgZmlsbD0iIzFkNGVkOCIgZmlsbC1vcGFjaXR5PSIwLjA4IiBzdHJva2U9IiMxZDRlZDgiLz4KPGcgZm9udC1mYW1pbHk9IkdlaXN0LCBzYW5zLXNlcmlmIiBmb250LXNpemU9IjEyIiBmb250LXdlaWdodD0iNjAwIiBmaWxsPSIjMTAxODI4Ij4KPHRleHQgeD0iNjAiIHk9IjE1MiI+QWdlbnQgcnVuPC90ZXh0Pgo8dGV4dCB4PSIzNDQiIHk9IjEyOCI+UmV2aWV3IGdhdGVzPC90ZXh0Pgo8dGV4dCB4PSI3MDAiIHk9IjE1MiI+QWR2aXNvciByZXZpZXc8L3RleHQ+Cjx0ZXh0IHg9IjEwMDQiIHk9IjEyOCI+UmVwbHk8L3RleHQ+Cjx0ZXh0IHg9IjM0MCIgeT0iMzY4Ij5JZGxlPC90ZXh0Pgo8dGV4dCB4PSI3MDAiIHk9IjUxMiI+QmxvY2tlciBmb2xsb3ctdXA8L3RleHQ+CjwvZz4KPGcgZm9udC1mYW1pbHk9IkdlaXN0IE1vbm8sIG1vbm9zcGFjZSIgZm9udC1zaXplPSI4IiBmaWxsPSIjNGM1NjY1Ij4KPHRleHQgeD0iNjAiIHk9IjE3NiI+YmVmb3JlX2FnZW50X3N0YXJ0OiBydW4gc3RhcnQ8L3RleHQ+Cjx0ZXh0IHg9IjYwIiB5PSIxOTYiPmNvbnRpbnVhdGlvbnMgc3RheSBpbiB0aGUgcnVuPC90ZXh0Pgo8dGV4dCB4PSIzNDQiIHk9IjE1MiI+YWR2aXNvciBvbiBmb3IgdGhpcyBicmFuY2g8L3RleHQ+Cjx0ZXh0IHg9IjM0NCIgeT0iMTc2Ij5VSSBhdmFpbGFibGU8L3RleHQ+Cjx0ZXh0IHg9IjM0NCIgeT0iMjAwIj5ub3QgYWJvcnRlZCwgc3RvcFJlYXNvbjogc3RvcDwvdGV4dD4KPHRleHQgeD0iMzQ0IiB5PSIyMjQiPmEgdG9vbCBjYWxsIGluIHRoaXMgcnVuPC90ZXh0Pgo8dGV4dCB4PSIzNDQiIHk9IjI0OCI+cnVuIHN0YXJ0IHJlY29yZGVkPC90ZXh0Pgo8dGV4dCB4PSI3MDAiIHk9IjE3NiI+TW9kZWwgVGFzayBwaS1hZHZpc29yL3JldmlldzwvdGV4dD4KPHRleHQgeD0iNzAwIiB5PSIxOTYiPmluIHRoZSBiYWNrZ3JvdW5kLCA5MCBzIGxpbWl0PC90ZXh0Pgo8dGV4dCB4PSIxMDA0IiB5PSIxNTIiPlBBU1M6IGluZm8gbm90aWNlPC90ZXh0Pgo8dGV4dCB4PSIxMDA0IiB5PSIxNzYiPm5pdCwgY29uY2Vybjogbm90ZXMgbm90aWNlPC90ZXh0Pgo8dGV4dCB4PSIxMDA0IiB5PSIyMDAiPmJsb2NrZXI6IG5vdGVzIHdhcm5pbmc8L3RleHQ+Cjx0ZXh0IHg9IjEwMDQiIHk9IjIyNCI+bWFsZm9ybWVkOiBvbmUgd2FybmluZyBwZXIgc2Vzc2lvbjwvdGV4dD4KPHRleHQgeD0iMTAwNCIgeT0iMjQ4Ij50aW1lb3V0IG9yIG1vZGVsIGVycm9yOiBvbmUgd2FybmluZzwvdGV4dD4KPHRleHQgeD0iMTAwNCIgeT0iMjcyIj5jYW5jZWxsZWQgb3Igc3RhbGU6IG5vIG5vdGljZTwvdGV4dD4KPHRleHQgeD0iMzQwIiB5PSIzOTIiPm5vIHJldmlldywgb3Igbm90ZXMgb25seTwvdGV4dD4KPHRleHQgeD0iMzQwIiB5PSI0MTIiPm5vIG5ldyB0dXJuPC90ZXh0Pgo8dGV4dCB4PSI3MDAiIHk9IjUzNiI+dmlzaWJsZSBwaS1hZHZpc29yLWJsb2NrZXI8L3RleHQ+Cjx0ZXh0IHg9IjcwMCIgeT0iNTU2Ij50cmlnZ2VyVHVybiwgb25jZSBwZXIgcHJvbXB0PC90ZXh0Pgo8L2c+Cjx0ZXh0IHg9IjM0NCIgeT0iMjc2IiBmb250LWZhbWlseT0iR2Vpc3QsIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iMTIiIGZpbGw9IiM0YzU2NjUiPkFsbCBnYXRlcyBtdXN0IHBhc3MuPC90ZXh0Pgo8cGF0aCBkPSJNNDAgNjQ0IEgxMjQwIiBzdHJva2U9IiMxMDE4MjgiIHN0cm9rZS1vcGFjaXR5PSIwLjEyIi8+Cjx0ZXh0IHg9IjQwIiB5PSI2ODAiIGZvbnQtZmFtaWx5PSJHZWlzdCwgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMiIgZmlsbD0iIzRjNTY2NSI+VGhlIGFkdmlzb3IgcmVhZHMgb25seSB0aGUgdXNlciBwcm9tcHQgYW5kIHRoZSBydW4gcmVjb3JkLiBUaGUgcmV2aWV3IHJ1bnMgaW4gdGhlIGJhY2tncm91bmQsIHNvIFBpIHN0YXlzIGlkbGUuPC90ZXh0Pgo8L3N2Zz4K) 1. A user prompt or a triggering custom message starts a run. Pi Advisor records where the run starts on the branch. 2. Other extensions can continue the run. All of their turns stay in the same run. 3. Pi settles the run. Pi Advisor does no review for a run without tool calls, an unfinished run, or a session without UI. 4. Pi Advisor sends one tool-free request to the advisor model in the background. The request contains the latest user prompt and the run record. 5. Pi shows the notes. For a `blocker` note when the editor is empty, Pi Advisor sends a visible `pi-advisor-blocker` follow-up message. The message starts a new run that fixes the blockers. 6. The advisor also examines that new run. It shows the notes, but it sends no other follow-up until the next user prompt. ## State and storage Pi Advisor keeps no files. `/advisor on` and `/advisor off` append a `pi-advisor` custom entry to the conversation. The latest entry on the current branch sets the state, so branch navigation, `/tree`, forks, and rewinds show the state of the selected branch. Each blocker follow-up is a visible `pi-advisor-blocker` message on the branch. Its `details` contain the notes. ## Limits and recovery | Limit | Behavior | Recovery | | --- | --- | --- | | Interactive only | The advisor does not run in print mode or other modes without UI. | Examine the run manually. | | No route | Pi shows a warning that names `/task-models`. The advisor does not use the session model. | Run `/task-models` and set a route for the `pi-advisor/review` profile. | | Time limit | The review stops after 90 seconds and Pi shows a warning. Pi shows no notes. | Send the next prompt. | | Cancel | A new prompt, a new run, branch navigation, `/advisor off`, or session exit cancels the review. Pi shows no notice. Escape in an idle session does not cancel it. | Send a prompt to cancel the review. | | Old reply | When the branch changes or Pi starts work before the reply arrives, Pi Advisor ignores the reply. | Send a prompt to start a new run. | | Model error | Pi shows a warning. Pi shows no notes. | Run `/task-models` to examine the route, or send the next prompt. | | Run record size | Each item is truncated to 4,000 characters, and the prompt to 8,000. The record keeps the newest 48,000 characters and marks earlier items as omitted. | Ask for a smaller run when early steps must be examined. | | One follow-up | A blocker sends one follow-up message for each user prompt. | Send a prompt to fix the remaining blockers. | | Draft in the editor | When the editor contains text, a blocker sends no follow-up message. Pi shows all notes and tells you to send a prompt. | Send a prompt to fix the blockers. | | Advice only | The advisor sees only the run record. Its notes can be wrong. | Examine each note before you accept it. |