pi-overwatch

Invisible Pi transcript sidecar monitor. It watches finalized transcript messages and tool executions, digests non-overlapping weighted transcript chunks with a separate model, emits pi-overwatch:result on Pi's extension event bus, contributes the latest output as a structured Pi Overwatch section to @taylorsatula/pi-hud, and writes JSONL observer notes under ~/.pi/agent/pi-overwatch/.

Each record includes structured metacognitive orientation: a summary, named entities, concrete grounding facts, code/config context, inferred musings, optional open questions/concerns, and a short observer-style narration of what the foreground model appears to be tracking while it works. The HUD contribution is omitted until the first monitor record is produced, then returns a compact nested JSON object with state/confidence, summary/orientation/narration, capped entity/fact/context/musing arrays, and chunk metadata (start_index_inclusive, end_index_exclusive, item_count, weight, threshold, total items, model).

Rhythm trigger

Pi Overwatch tracks normalized transcript items (user, assistant, tool_call, tool_result) and accumulates weights until the chunk reaches the trigger threshold. Defaults:

Item	Weight
user	1.0
assistant	0.8
tool_call	0.20
tool_result	0.35
errored tool_result	0.8

The default trigger threshold is 8.0. Each JSONL record stores chunkWeight and triggerWeight.

Output contract

Pi Overwatch asks the monitor model for normal text output containing exactly one raw JSON object. It does not pass tools or tool_choice; OpenRouter/local models that try to enter tool-use mode are avoided by contract. The extension parses the text response as JSON, accepting bare JSON, fenced JSON, or the first balanced-looking object embedded in text.

Usage

Install or enable this local package by adding it to ~/.pi/agent/settings.json packages:

"/Users/taylut/.pi/packages/pi-overwatch"

Configure the monitor model in ~/.pi/agent/settings.json:

"piOverwatch": {
  "provider": "openrouter",
  "model": "google/gemma-4-26b-a4b-it"
}

PI_OVERWATCH_MODEL="provider:model-id" can override JSON config for one process. The legacy PI_TRANSCRIPT_MONITOR_MODEL variable is also accepted while migrating.

Command

• /pi-overwatch — show the latest in-memory structured output as a notification.

HUD integration

When @taylorsatula/pi-hud is loaded, Pi Overwatch emits a hud_section contribution with label Pi Overwatch. The section value is structured JSON, not a string blob, so the foreground model receives the latest sidecar observer note as a nested HUD object without writing it to the transcript. After a new sidecar record is produced, Pi Overwatch emits hud_refresh so pi-hud rebuilds its cached payload immediately instead of waiting for the next standard refresh event.