Security hooks for Pi. Prevents dangerous operations, protects env files, gates destructive commands.

[!WARNING] I am not responsible for any issues, damage, or data loss caused by agents, even when using Guardrails. Guardrails is not a sandbox and does not guarantee safety. You are responsible for adding and maintaining rules that prevent dangerous operations in your environment; do not rely on the defaults alone.
Guardrails adds safety checks to Pi so agents are less likely to read secrets, write protected files, access paths outside the workspace, or run dangerous shell commands by accident.
The package installs four Pi extensions:
pi install npm:@aliou/pi-guardrails
After installing, run the onboarding command to choose a starting setup: /guardrails:onboarding. You can change everything later with /guardrails:settings.
Protects files like .env, private keys, local credentials, database dumps, or any project-specific path you do not want Pi to read or modify without clear intent. Rules respect the current working directory by default and are configurable in the settings UI.
Use /guardrails:examples to add common policy and command presets without replacing your existing config.
Checks tool calls that target paths outside the current working directory. It can allow, block, or ask before Pi accesses files elsewhere on your machine; in ask mode, you can allow a file or a directory once, for the session, or always. By default, checks apply to both reads and writes outside the workspace, and “always” grants are saved to the project config — both are configurable through /guardrails:settings.
Detects dangerous bash commands before they run — recursive deletes, privileged commands, disk formatting, broad permission changes, and any custom patterns you configure. You can allow once, allow for the session, deny, or decline and stop, which also aborts the current turn. Auto-deny patterns can set terminate: true to end the agent’s turn after blocking, so it does not retry the blocked command.
Command, policy, and path checks also look inside command and process substitutions, so a risky call wrapped in $(...) is still caught.
The included Herdr adapter reports active Guardrails approval prompts through Herdr’s herdr:blocked event, so Herdr can show the Pi pane as blocked while a prompt waits for a decision. It has no configuration and no effect unless Herdr’s Pi integration is active.
Approval prompts also report blocked program status (OSC 7501) natively through the blocked option of ctx.ui.custom(), so terminals such as Rex show Pi as blocked while a prompt waits; no extension is needed for that anymore.
Before permission-gate or path-access prompts you, other extensions can decide for you. If every registered delegate allows the action, it runs without a prompt; if any blocks it, it is blocked; anything else, including a timeout, falls back to the usual prompt. Each decision shows up under the tool call as a [guardrails] line.
See docs/decision-delegation.md for the rules and how to write a delegate, with runnable examples in examples/delegates/ — including a classifier-model delegate you can copy and tune for your own policies.
Guardrails emits paired events on Pi’s shared event bus: guardrails:prompt:opened when an interactive prompt starts waiting for input and guardrails:prompt:closed when it stops. Both carry the same prompt.id for correlation.
Decision delegation events are listed in docs/decision-delegation.md.
Most configuration happens through the interactive settings UI (/guardrails:settings). Advanced users can edit the settings file directly:
~/.pi/agent/extensions/guardrails.json.pi/extensions/guardrails.jsonProject settings apply only after Pi trusts the folder (/trust, then restart Pi). Until then, untrusted project files are ignored and left unchanged, while global settings and built-in protections still apply. Set pathAccess.alwaysScope to "global" to save “always” path grants without trusting the project.
Approval prompts wait for prompts.inputGuardMs milliseconds of input inactivity before accepting an answer (default 1000). Each keypress restarts the delay, preventing keystrokes intended for the editor from answering a prompt that just opened. Set it to 0 to disable the guard.
Saved files include a $schema field for editor autocomplete and validation; the schema is committed at schema.json.
Pi is designed to make agent safety extensible. Guardrails focuses on deterministic, configurable file policies, path access control, and dangerous-command prompts. See pi.dev/packages for the full registry.
Closest alternatives:
.env files, and a sandbox guard.You can also make your own: start from the Pi permission gate example and ask Pi to customize it for your workflow.
pnpm test # Run tests
pnpm test:watch # Run tests in watch mode
pnpm typecheck # Type check
pnpm lint # Lint
pnpm format # Format
pnpm gen:schema # Regenerate schema.json
pnpm check:schema # Verify schema.json is current