$ cat ~/map/pi-heed.md

pi-heed

Turns what you said into runtime constraints and checks every side-effecting tool call against them before it runs.

extensions✓ Sep 20

Run pi install git:github.com/Nyarlathoteppppp/pi-heed; rules work immediately and the extension starts in shadow mode — /heed on switches to enforce, and a Jev key via TYPESAFE_API_KEY or OPENROUTER_API_KEY unlocks the semantic layer.

## TL;DR

A pi extension that turns what you say in the conversation into runtime constraints: stated rules like review-only or protected paths are checked against every side-effecting tool call before it runs, survive compaction as persisted session state, and stay in shadow mode until you switch them on.

## Key points

• $Conversational policy, not a keyword list: each rule carries an effect (DENY, ALLOW, REQUIRE_CONFIRMATION, REQUIRE_BEFORE), an action (modify, install_deps, git_push, git_commit, custom), a resource scope, exceptions, a lifetime (once expires after first use, run expires when the run ends), and a status; resolution per call is most specific resource first (file beats dir beats tests beats everything), then the more specific action, then the newer instruction — and nothing is ever deleted.
• $Compaction-proof by construction: every policy change is an op persisted in the session, so after a reload or compaction the state replays to exactly what it was, without calling Jev again.
• $Jev's job is narrow: it never writes policy — it classifies how each existing policy changed (KEEP, LIFT, NARROW, EXCEPTION, REPLACE, UNKNOWN), answers whether a message is your go-ahead to start changing things, and supplies signals; pi-heed applies only confident answers, takes resources from your message never from Jev, and anything uncertain changes nothing.
• $What gets checked: read-only, don't-touch-tests, and no-new-dependencies rules are decided by rules plus Jev, while protected-path rules are decided by rules alone; free-text prohibitions such as never calling the production API go through a Jev violates/complies/insufficient question; blind retries of the same failing command are caught and annotated with evidence — while reads (read, grep, find, ls, non-mutating shell) are never checked.
• $Safety properties: off, shadow, and enforce modes persist per session; a Jev error or a 2.5-second timeout fails open as if pi-heed were not installed; it never starts a turn, verdicts that land after Esc or a new prompt are discarded, interventions are capped at 3 per agent run, and text injected by extensions never becomes a constraint.
• $Measured against its own benchmark of 79 scripted sessions and 261 labelled decisions plus replays of the author's real pi sessions: models broke a rule that changed mid-session 8 of 13 times unaided and zero times with pi-heed enforcing, and rules-only mode still catches most violations with no Jev key and zero API cost.

## FAQ

## References

• README ↗
• Benchmark method ↗

Last updated: Sep 20, 2026