@henryqw/pi-advisor

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

pi install npm:@henryqw/pi-advisor

Requires Pi 1.5.0 or later in the 1.x series.

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

Use

Type /advisor to see filtered, described choices for on, off, and status.

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.

The advisor is off by default.

Results

Flow

flowchart TD
    accTitle: Pi Advisor review flow
    accDescr: A user prompt or triggering custom message starts a run. Other extensions can continue that same run before it settles. Review needs the advisor on for the branch, a user interface, a recorded run start, tool calls, and a completed run without abort. The background review gets only the latest user prompt and bounded run record, with no tools. No route means no session-model fallback. A blocker starts a new run only when the editor is empty and no blocker follow-up was sent since the latest user prompt. Cancelled or stale replies are ignored.
    Run["Agent run"] --> Settle["Run settles"]
    Run -->|Other extension continues| Run
    Settle --> Gates{"All review conditions met?"}
    Gates -->|No| End["No new turn"]
    Gates -->|Yes| Route{"Review route available?"}
    Route -->|No| Missing["Warn; no session-model fallback"]
    Missing --> End
    Route -->|Yes| Review["Background review; no tools; 90 seconds"]
    Review -->|Cancelled or stale| End
    Review -->|Timeout or model error| Warning["Show warning"]
    Warning --> End
    Review -->|Reply| Valid{"Valid reply within 8,000 characters?"}
    Valid -->|No| Malformed["Warn once per session"]
    Malformed --> End
    Valid -->|Yes| Notes["Show PASS or graded notes"]
    Notes --> Blocker{"Blocker, empty editor, follow-up unused?"}
    Blocker -->|No| End
    Blocker -->|Yes| FollowUp["Visible blocker follow-up; once per prompt"]
    FollowUp --> Run

Read the static advisor flow diagram on npm or without a Mermaid renderer.

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