ZiChuanLan/pi-purge

If you want to know how much a coding agent's behavior comes from its built-in system prompt versus your instructions, this extension gives you a session-level switch to change that variable instead of fighting it.

The problem

You have a prompt file you believe makes pi behave better, but the agent's bundled system prompt is still there, so a bad result is ambiguous: was your instruction ignored, or did the harness framing outweigh it? Normally the only way to test is to edit the harness prompt, which is fragile and hard to reverse. With pi-purge you run the same request under stock, trimmed, and prompt-only configurations by toggling a mode, and /purge status tells you what the previous turn actually changed. The result is a comparison you can repeat, rather than a vague sense that your prompt "works."

What's different

pi-purge does not try to out-shout the built-in prompt. In replace mode it removes pi's built-in assistant identity line and bundled documentation section, keeping the tool list, guidelines and project context. In strict mode only your prompt plus the current working directory is sent. That subtraction is the interesting mechanism, and the README is candid about its cost: strict also drops AGENTS.md/project context, the skills list, and prompt text injected by other extensions, so its results are not comparable to a normal session. append is the least invasive mode and, the README says, usually yields the weakest signal because later harness sections still carry weight. The default is strict, which is also the mode where the persona competes least with other framing.

State handling is deliberately minimal. Scope is the session; every startup, new, resume or reload begins disabled, and nothing is written to disk. That means quitting pi always restores stock behavior, but it also means you must re-enable the rewrite after each restart or resume. To avoid retyping, PI_PURGE_SOURCE can point at an absolute prompt path from the process environment without storing state.

Who should try it

Good fit: someone doing prompt engineering or regression testing on the pi coding agent who wants an A/B run of the same task with the harness prompt present, trimmed, or absent. The three named modes map directly onto that experiment design, and the bundled example prompt means a first run needs no extra files.

Poor fit: anyone who wants a permanent persona for daily coding. Nothing persists across sessions by design, and the strict isolation that makes it useful for experiments is exactly what removes the project context a normal session depends on. If you only want to append instructions on top of normal pi behavior, append mode exists, but the README itself warns the differences may be small.

Requirements and limitations

You need an existing pi installation (@earendil-works/pi-coding-agent), since this is an extension, not a standalone agent. Install is via a pinned git ref or npm, then /purge inside a session; the project README describes the single hook and test suite. Custom prompts must be a file you point to with /purge source <path>; after editing that file, /purge reload re-reads it. The ongoing upkeep is remembering to re-enable per session and re-running reload after edits.

The bigger limitation is interpretive: replace still leaves harness text behind, and other extensions may append prompt sections after this one runs, so only strict isolates your persona cleanly. The README also flags that results from strict are not comparable to a normal session. Treat it as a lab instrument, not a production configuration. The README credits the mechanism and bundled prompt as ported from the dsh-purge project.

HotRepo's take

Six days after creation, the project appeared at #25 on HotRepo's NEW-REPOSITORY board for JavaScript with 299 total stars on 2026-10-24. That is a single dated snapshot, not a growth measurement, and comparable daily-board history is insufficient to judge persistence. The design is small and honest about its trade-offs; the main thing to check before adopting is whether your workflow tolerates per-session re-enabling and the context loss in strict mode.