pi-advisor

A "second model" turn reviewer for pi. After every agent run settles, pi-advisor sends a compact transcript of that run to a configured advisor model and emits its critique as nit / concern / blocker notes. Notes are delivered with sendMessage(deliverAs: "nextTurn"), so they ride the next user input — zero extra turns are ever generated.

How it works

1. On agent_end the run's messages are captured (kept only in memory).
2. On agent_settled (so auto-retry/compaction/follow-ups are finished) a compact transcript is built: role + text per message, tool calls with args (~200 chars), tool results (~300 chars), hard cap ~30k chars. Runs without ~200 chars of assistant text are skipped.
3. A subprocess runs pi -p --no-session --no-extensions --no-skills --no-prompt-templates --no-themes --no-context-files --no-tools --model <model> "<prompt>" (async, fire-and-forget, 120s timeout). The model must answer with a JSON array only.
4. Output is parsed tolerantly (code fences/prose stripped, first JSON array), each item is validated, over-long notes are truncated, and malformed items are quarantined.
5. Notes are filtered by minSeverity, capped at maxNotesPerTurn (blockers first), and deduplicated for the session.
6. Every note is appended as an advisor-note session entry and sent as a custom advisor-note message (deliverAs: "nextTurn"). Only when interruptBlockers is on and the note is a blocker is it also shown immediately via ui.notify(...) — never as a steer, which would create a spontaneous turn while idle.

Config

In ~/.pi/agent/settings.json under the advisor key (or via /advisor):

{
  "advisor": {
    "enabled": true,
    "model": "openai/gpt-4o-mini",
    "minSeverity": "concern",
    "maxNotesPerTurn": 2,
    "interruptBlockers": false
  }
}

| Key | Default | Meaning | |-----|---------|---------| | enabled | false | Master switch (dormant when off). | | model | (unset) | Advisor model provider/model. Missing ⇒ dormant. | | minSeverity | concern | Drop notes below this: nit < concern < blocker. | | maxNotesPerTurn | 2 | Max notes delivered per turn (blockers prioritized). | | interruptBlockers | false | Also pop a desktop-level warning for blockers. |

Commands

/advisor                          # status
/advisor on | off                 # enable / disable
/advisor model <provider/model>   # set advisor model
/advisor severity <nit|concern|blocker>
/advisor maxnotes <n>             # positive integer
/advisor interrupt on | off       # blocker interruption

All commands persist to settings.json atomically (temp file + rename), like pi's own settings writes.

Privacy

To produce notes, pi-advisor sends the current run's transcript to the configured advisor model (*"advisor"*).model). Only the run's messages travel — never the entire session, credentials, or config — but the model provider sees that transcript. Disable with advisor: { "enabled": false } or remove the model key.