pi-read-guard

A pi extension that prevents massive unbudgeted full-file reads, steering the agent to offset/limit or search tools.

Enforcement lives in a tool_call hook, so it adds zero tokens to the system prompt.

Rules

• read on any file with more than maxReadLines (default 200) without offset or limit is blocked.
• Images, PDFs and any binary file are never blocked (a NUL byte in the first 8 KB, or an image/PDF extension): their newline bytes are noise, and blocking them would break screenshots.
• The model is steered to read a slice with offset/limit, or to search first (rg, codegraph_search).

Install

From npm:

pi install npm:pi-read-guard

Or from git:

pi install git:github.com/sorinirimies/pi-read-guard

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 full read of a large file is blocked, the agent reads a slice (60 lines instead of 319):

No bypass by spelling: ~/… and @… paths (which pi expands before reading) are blocked just like the plain one:

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

Commands

• /read-guard: status and block count
• /read-guard off / on: disable / enable for this session
• /read-guard allow <path>: allow one full read of <path> this session

Config (optional)

~/.pi/agent/read-guard.json:

{ "maxReadLines": 200, "ignore": ["*.md", "*.json"] }

Security notes

• A token saver, not a sandbox. It guards pi's read tool. An agent can still read files through bash (cat); the guard keeps accidental full-file reads out of your context, nothing more.
• Same path as the tool. Paths are resolved exactly like pi's own read (@file, ~/file, file://, Unicode spaces, Windows shell paths, and the macOS filename variants it falls back to), 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".
• 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