# pi-notifications

Audio alerts for pi agent events via `afplay`.

## What it does

Plays a sound when the agent finishes a turn, so you can step away and get alerted when input is needed.

## Configuration

| Env var | Default | Description |
|---------|---------|-------------|
| `PI_NOTIFICATIONS_ENABLED` | `true` | Set to `false` to disable all notifications |
| `PI_NOTIFICATION_AGENT_END` | `true` | Play sound when agent finishes |
| `PI_NOTIFICATION_AUDIO` | `/System/Library/Sounds/Glass.aiff` | Path to audio file (.aiff/.wav/.mp3) |
| `PI_NOTIFICATION_DEBUG` | `false` | Show visible steer signal instead of playing sound |

## Debugging

- **`PI_NOTIFICATION_DEBUG=true`** — emits a steer message in the TUI instead of playing sound (great for loop testing)
- **Standalone tester:** `node --input-type=module -e "import {createJiti} from './node_modules/.pnpm/@mariozechner+jiti@2.6.5/node_modules/@mariozechner/jiti/lib/jiti.mjs'; const jiti = createJiti(); await jiti.import('./packages/pi-notifications/src/test-notify.ts');"`

## Available macOS sounds

```
/System/Library/Sounds/Bottle.aiff
/System/Library/Sounds/Cork.aiff
/System/Library/Sounds/Frog.aiff
/System/Library/Sounds/Glass.aiff       ← default
/System/Library/Sounds/Hero.aiff
/System/Library/Sounds/Morse.aiff
/System/Library/Sounds/Ping.aiff
/System/Library/Sounds/Pop.aiff
/System/Library/Sounds/Submarine.aiff
/System/Library/Sounds/Sosumi.aiff
/System/Library/Sounds/Tink.aiff
```

## Usage

Add to `~/.pi/agent/settings.json`:

```json
{
  "packages": [
    "/path/to/packages/pi-notifications"
  ]
}
```

Then reload pi:

```bash
/reload
```

## License

MIT