# 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:

```bash
GUARDRAILS_NOTIFY_BACKEND=terminal pi
```

## Install

From npm:

```bash
pi install npm:guardrails-notify@0.1.0
```

From a local checkout:

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

For one-off testing without installing:

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

## Publish

```bash
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:

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

Then publish with:

```bash
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.