pi-sensitive-guard

Sensitive-file protection extension for the Pi coding agent.

pi-sensitive-guard blocks unsafe access to secret-bearing files, scans writes and Git diffs for common credential patterns, and can optionally return redacted protected reads for trusted workflows.

Features

• Protects .env, credential, private-key, and secret files from reads, writes, deletes, shell commands, commits, and pushes.
• Scans write/edit content and Git commit/push diffs for common high-severity secret patterns.
• Keeps runtime configuration simple with top-level enable/disable, debug logging, read-redaction controls, protected-edit controls, and the /sensitive-guard menu.
• Allows optional non-sensitive edits to protected files when protectedFileEdits.enabled is explicitly enabled.
• Supports both legacy text replacements and structured edit line operations for protected-file safe-edit checks.
• Redacts structured JSON values, key/value assignments, embedded assignments, private keys, and known secret patterns while preserving safe output shape.
• Writes debug output only to the extension-local debug/ directory when debug is enabled.
• Emits/logs blocked-event metadata after redacting sensitive values.

Installation

Local extension folder

Place this folder in one of Pi's auto-discovery locations:

# Global default (when PI_CODING_AGENT_DIR is unset)
~/.pi/agent/extensions/pi-sensitive-guard

# Project-specific
.pi/extensions/pi-sensitive-guard

npm package

pi install npm:pi-sensitive-guard

Git repository

pi install git:github.com/MasuRii/pi-sensitive-guard

Usage

pi-sensitive-guard runs automatically after Pi loads the extension. It inspects tool calls before execution and blocks protected file access or detected secret writes with a clear TUI notification.

Typical protected flows include:

• reading .env, key, token, credential, and private-key files;
• writing or editing content that matches high-confidence secret patterns;
• shell commands that read, write, delete, commit, or push protected secret-bearing files;
• optional protected reads with redacted output when readRedaction.enabled is set to true.

/sensitive-guard command

Use /sensitive-guard inside Pi to open the interactive configuration menu. The menu can toggle the guard, read redaction, shell-output redaction, blocked-event logging, debug logging, content scanning, protected-file safe edits, and redaction limits without editing JSON by hand.

Additional command forms:

• /sensitive-guard status shows the resolved runtime configuration summary.
• /sensitive-guard edit opens the raw config.json editor.

After changing configuration, run /reload or restart Pi so the guard reloads its rules.

Configuration

Runtime configuration is stored at:

Default global path: ~/.pi/agent/extensions/pi-sensitive-guard/config.json
Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-sensitive-guard/config.json when PI_CODING_AGENT_DIR is set

config.json is a user-local runtime file. It is gitignored and excluded from npm package contents. A starter template is included at config/config.example.json.

Configuration options

Option	Type	Default	Description
enabled	boolean	true	Enable or disable all sensitive-file protection.
debug	boolean	false	Enable file-only debug logging under debug/debug.log.
readRedaction.enabled	boolean	false	Allow redacted read output instead of hard-blocking eligible protected reads.
readRedaction.includeShellOutput	boolean	false	Also redact shell-command output when protected files are read through shell commands.
readRedaction.scope	protectedOnly | allOutput	protectedOnly	Choose whether redaction applies only to protected read flows or to every read/shell output path covered by the redaction settings.
protectedFileEdits.enabled	boolean	false	Allow safe non-sensitive write/edit changes to protected files; sensitive key/value, structure, or secret-bearing edits remain blocked.

When protected-file edits are enabled, the guard recognizes exact oldText/newText replacements, replace_text, and structured line-edit operations. The proposed result is still blocked if it changes sensitive keys or structure, introduces detected secret patterns, or cannot be evaluated safely.

Example config

{
  "enabled": true,
  "debug": false,
  "readRedaction": {
    "enabled": false,
    "includeShellOutput": false,
    "scope": "protectedOnly"
  },
  "blockedEvents": {
    "emit": true,
    "log": true,
    "logPath": "logs/blocked-events.jsonl"
  },
  "protectedFileEdits": {
    "enabled": false
  }
}

Changes take effect after /reload.

Validation

npm run build
npm run lint
npm run test
npm run check
npm run package:dry-run

Publishing

The package metadata follows the same publish-ready shape used by established Pi extensions:

• entrypoint: index.ts
• package exports: . → ./index.ts
• Pi extension manifest: pi.extensions
• published files: source, README, changelog, license, and config template
• runtime config.json, debug/, logs/, and test artifacts excluded from npm publication

Note

The package requires Node.js >=22 because its shell parser dependency declares the same minimum engine.

Related Pi Extensions

• pi-permission-system — Permission enforcement for tool and command access
• pi-multi-auth — Multi-provider credential management, OAuth login, and account rotation
• pi-tool-display — Compact tool rendering and diff visualization
• pi-rtk-optimizer — RTK command rewriting and output compaction

License

MIT