guardrails-notify

Pi extension that sends cmux, terminal, and native notifications when guardrails waits for approval.

Packages

Package details

extension

Install guardrails-notify from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:guardrails-notify
Package
guardrails-notify
Version
0.1.0
Published
Jun 4, 2026
Downloads
38/mo · 9/wk
Author
jpballares
License
MIT
Types
extension
Size
9.2 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./extensions/guardrails-notify.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

guardrails-notify

A Pi package that displays notifications when the Guardrails extension is waiting for user approval.

What it does

This extension listens on Pi's shared extension event bus for Guardrails approval events:

  • guardrails:action:prompted
  • guardrails:action:blocked

When approval is requested, it:

  • rings the terminal bell when stdout is a TTY,
  • shows a Pi UI warning notification,
  • sets a temporary Pi status message,
  • sends one external notification through the first available backend.

External notification backend order in auto mode:

  1. cmux notify
  2. terminal OSC notification escapes for supported terminals such as Ghostty, iTerm2, WezTerm, and foot
  3. native OS fallback: osascript on macOS or notify-send on Linux

The status message is cleared when Guardrails emits a blocked event or when a tool result is received.

Requirements

  • Pi coding agent
  • Node.js 20 or newer
  • Optional: cmux, a terminal with OSC notification support, osascript, or notify-send

The extension searches for cmux in this order:

  1. CMUX_BIN environment variable
  2. cmux on PATH
  3. ~/Applications/cmux.app/Contents/Resources/bin/cmux
  4. /Applications/cmux.app/Contents/Resources/bin/cmux

Notification backend selection

By default, the extension uses GUARDRAILS_NOTIFY_BACKEND=auto.

Supported values:

  • auto - use the first available external backend
  • cmux - use only cmux notify
  • terminal - use only terminal OSC notification escapes
  • native - use only osascript on macOS or notify-send on Linux
  • off, none, false, or 0 - disable external notifications

Example:

GUARDRAILS_NOTIFY_BACKEND=terminal pi

Install

From npm:

pi install npm:guardrails-notify@0.1.0

From a local checkout:

pi install /absolute/path/to/guardrails-notify

For one-off testing without installing:

pi -e /absolute/path/to/guardrails-notify

Publish

npm pack --dry-run
npm publish

If the npm package name is already taken, rename the package in package.json or publish under a scope:

{
  "name": "@your-scope/guardrails-notify"
}

Then publish with:

npm publish --access public

Notes

This package only reacts to events. It does not implement Guardrails approval logic by itself. Another extension must emit the Guardrails events listed above.