π pi-edit-guard
Exact /undo, stale-edit protection and a loop breaker for the π (pi) coding agent. The extension blocks edits to files that changed since the agent read them, snapshots the project before each run so /undo restores it exactly, and stops repeated identical tool calls. Nothing is written into your project or its .git.
pi install npm:@lenard9191/pi-edit-guard
What it does
- Freshness — a write to an existing file needs a read of that file, still in the model's context, whose content hash still matches the disk (compare-and-swap on content). An unread or changed file is blocked; one
readrepairs it. Paths resolve exactly as π's tools resolve them, through symlinks. - Snapshots and
/undo— before the first call of a run that can change files, the project is snapshotted into a private git store under~/.pi/agent/pi-edit-guard/./undopreviews the paths and restores content, executable bits, symlinks and the case of names exactly, deletes files the run created, and can itself be reversed. - Loop breaker — the third identical call with nothing changed in between is blocked for tools that depend only on the files, and flagged for shell, web and other tools. A command that fails again after changes gets a notice to stop and re-think.
The project's .git is only read. Requires π ≥ 1.2.0, Node ≥ 22.18 and git; no runtime dependencies; MIT. Tested on macOS, Linux and Windows.
What the agent sees
edit-guard: src/app.ts exists but was not read in this context. Read it, then retry.
edit-guard: src/app.ts changed since you read it (call #12). Read it again, then retry.
edit-guard: identical call #3 with no change in between; the result would be identical. Change the input or the state first.
edit-guard: this command failed 2 times after changes. Stop. Re-read the relevant code top-down, state which assumption was wrong, and choose a different approach before the next edit.Commands
/undo | restore the files to the state before the latest run that changed something; shows the paths that change and asks first |
/undo <n> | the state before run n of this session |
/undo pre-undo-<k> | reverse undo k |
/checkpoints | this session's checkpoints and how many paths differ from now |
/guard | status and coverage; /guard on|off and /guard freshness|snapshots|loop on|off switch parts for the session |
The package also ships an Agent Skill (/skill:edit-guard) that the model loads on demand to explain the guard's messages and to point you to /undo when you ask it to revert its work. Full reference: README.
Performance
Measured on nine public repositories (express, flask, ripgrep, cobra, git, rails, django, react, symfony): the freshness check takes about 0.1 ms per write; a snapshot after the first takes 60–320 ms; an /undo of about 100 changed paths takes 0.2–0.9 s. The first snapshot of a project (0.1–5.6 s) runs in the background from the session's first prompt. Method and numbers: README.
FAQ
Does it work with Claude Code, Cursor or Codex?
No. It is an extension for the π coding agent only: it works through π's extension API (tool-call events, session entries and commands).
Does it write into my project or its .git?
No. Its state lives under ~/.pi/agent/pi-edit-guard/. The project's .git is only read (rev-parse, ls-files): your commits, index, branches and stash are never touched. Only /undo writes project files, and only the ones that differ.
How is /undo different from git checkout or git stash?
/undo restores the state before an agent run: every file git sees in the project (tracked, and untracked but not ignored), the ignored files a write tool changed, executable bits, symlinks and the case of names. Files the run created are deleted. It shows the paths first, touches only those, and leaves your commits, index, branches and stash alone. It takes a pre-undo checkpoint first, so /undo pre-undo-<k> reverses it.
Why was the agent's edit blocked?
The file is not as the agent last read it: the agent did not read it in the current context, or its content changed since (you, a formatter or another agent edited it). One read repairs it. The block exists so that the agent never overwrites a change it has not seen.
Does it slow the agent down?
The freshness check takes about 0.1 ms per write. A snapshot after the first takes 60–320 ms on nine public repositories, from express to symfony. The first snapshot of a project runs in the background from the session's first prompt.
Can the agent undo its own changes?
No. /undo is a command for you, because throwing away changes in the working tree is your decision. The agent reverts its own work with edits. The bundled skill tells the agent to point you to /undo instead of running git checkout, git stash or git reset.
Does it work on Windows?
Yes, with Git for Windows, which π needs for its bash tool. CI runs every test on Windows, macOS and Linux. On Windows, a symlink can be restored only with Developer Mode on or with administrator rights.