pi-edit-first

A pi extension that cuts output tokens by making the agent edit, not rewrite.

Enforcement lives in a tool_call hook, so it adds zero tokens to the system prompt. The model only sees a one-line reason when a call is blocked.

Rules

Install

From npm:

pi install npm:pi-edit-first

Or from git:

pi install git:github.com/sorinirimies/pi-edit-first

Applies to every pi session (including pi run as an external agent in editors).

Previews

Recorded from a real pi with only this plugin loaded; a small scripted mock model plays the agent, so you see the real guard reacting to real tool calls.

A whole-file rewrite is blocked, the agent makes a targeted edit (one line added, not 62 rewritten):

Hand-written manifests are blocked too (scaffold with the real tool instead):

Commands: status and block count, off / on, and allow <path> for one deliberate rewrite:

Commands

• /edit-first: status and block count
• /edit-first off / on: disable / enable for this session
• /edit-first allow <path>: allow the next full rewrite of <path> (one-shot; run it again for another)

Config (optional)

~/.pi/agent/edit-first.json:

{ "maxWriteLines": 40, "scaffold": true, "ignore": ["CHANGELOG.md", "*.lock"] }

ignore globs (* = anything but /, ? = one such character) match the path relative to the working directory or the file name, however the path is spelled (./x, @x, absolute, \).

Notes

• A block costs one extra round trip, far cheaper than a whole-file rewrite.
• Only affects the write tool; edit is never blocked.
• Line counts match wc -l (a trailing newline is not an extra line).
• Does not affect other agents (e.g. Zed's native agent).

Security notes

• A token saver, not a sandbox. It guards pi's write tool. An agent can still write files through bash; the guard exists to keep wasteful rewrites out of your context, not to confine the agent.
• Same path as the tool. Paths are resolved exactly like pi's own tools (@file, ~/file, file://, Unicode spaces, Windows shell paths), so those spellings can't slip past it. A contract test compares it with pi's real resolveToCwd.
• Fails open. pi blocks a tool when a tool_call handler throws, so any unexpected error here means "allow": the guard can never stop legitimate work.
• Constant memory. Line counts are streamed (64 KB chunks, early exit), never the whole file.
• No network access, no shell commands, zero runtime dependencies.

Development

bun install
just check          # typecheck + tests + pack check + nushell tests (what CI runs)
just test           # bun test only (with coverage)
just coverage       # tests + a coverage table
just push-all       # push main to every configured remote (origin + the Gitea instances); `just --list` has pull-all, push-tags-all, release-all, the *-force and sync-gitea-* variants

Coverage: every bun test collects coverage (bunfig.toml) and fails below 95% lines / 95% functions. CI shows the table on the run page and uploads lcov.info.

CI scripts are nushell (scripts/), the same ones locally and in GitHub / Gitea Actions. just --list shows every task.

Demo recordings

The GIFs above live in examples/vhs/generated/ and are stored with Git LFS (git lfs install once). They are recorded with VHS from a real pi that loads only this extension, on synthetic data (examples/vhs/fixture.sh), never from real files, sessions or credentials. The agent is a scripted mock model (examples/vhs/mock-llm.ts), so the recording is repeatable.

just vhs-all          # every tape (examples/vhs/*.tape): needs vhs, ttyd, ffmpeg, pi, bun, python3
just vhs-tape overview  # one tape
just vhs-list         # list the tapes
just demo             # try it yourself in a real pi on the same synthetic data

Releases (automatic)

So library updates need no human: they are merged once CI passes, built, versioned and published as a patch. A downgrade, a failing check, or a major update stops the chain and waits for review.

Release from CI: Actions → Release → Run workflow with a bump (patch, minor, major), or just release-ci minor: runs the gate, bumps, writes the changelog, tags, pushes and publishes. Manual release: just release patch (or minor / major / X.Y.Z) bumps, tags and pushes to GitHub; just release-all patch pushes to every configured remote; just push-release-all pushes an existing bump.

Secrets (repo settings): NPM_TOKEN is an npm granular access token with publish rights and "bypass 2FA" (required for CI publishing). GH_PAT (classic PAT, repo + workflow: needed to auto-merge GitHub Actions bumps; also lets a tag push trigger the release itself). Optional: GITEA_TOKEN (Gitea).

Commits follow Conventional Commits; the changelog is generated by git-cliff.

Related plugins

Four small pi extensions that save tokens without adding anything to the system prompt:

pi install npm:pi-edit-first
pi install npm:pi-read-guard
pi install npm:pi-tokenburn
pi install npm:pi-context-diet

MIT