npm package: @0xkobold/pi-alerts
Description: Customizable chimes and notifications for pi
Latest version: 0.1.0

# pi-alerts

A pi extension that plays customizable chimes and notifications when tasks are complete.

## Features

- **Beep Mode**: Simple system beep or Glass-like tone (cross-platform)
- **Custom Notes/Songs**: Play any note or melody using notation like `C4:200,E4:200,G4:400`
- **Native Notifications**: System notifications on macOS, Linux, or Windows
- **Text-to-Speech**: Announce completion with a spoken message
- **Volume Control**: Adjust alert volume (0-100%)
- **Cross-Platform**: Works on macOS, Linux, and Windows
- **Bundled Skill**: "Keep Me Posted" skill for notification workflows

## Installation

### Extension Only

```bash
# Create symlink to load the extension
ln -s /path/to/pi-alerts/index.ts ~/.pi/agent/extensions/pi-alerts.ts
```

Then restart pi or run `/reload`.

### Full Package (Extension + Skill)

```bash
# Symlink extension
ln -s /path/to/pi-alerts/index.ts ~/.pi/agent/extensions/pi-alerts.ts

# Symlink skill
ln -s /path/to/pi-alerts/skills/keep-me-posted ~/.pi/agent/skills/
```

## Usage

### Tool: `task_done_chime`

Use in your prompts when you want to be notified when a task finishes:

```javascript
// Basic beep alert with default settings
Use the task_done_chime tool when you're done.

// Custom chime
Use task_done_chime with mode="tone" and customSong="C5:200,E5:200,G5:400"

// System notification
Use task_done_chime with mode="notification" and title="Build Complete"

// Text-to-speech
Use task_done_chime with mode="speech" and customText="Task finished, ready for next!"
```

### Commands

- `/alert` - Show current settings
- `/alert status` - Display detailed settings in widget
- `/alert test` - Test current alert
- `/alert test tone` - Test specific mode

### Configuration

| Command | Description |
|---------|-------------|
| `/alert mode [beep\|tone\|speech\|notification\|silent]` | Set default mode |
| `/alert sound [Glass\|Tink\|Pop\|...]` | Choose beep sound (macOS) |
| `/alert beeps [1-10]` | Number of beeps |
| `/alert delay [50-2000]` | Delay between beeps (ms) |
| `/alert song [C4:200,...]` | Set custom melody |
| `/alert text [message]` | Set speech text |
| `/alert title [title]` | Set notification title |
| `/alert volume [0-100]` | Set volume level |
| `/alert sound list` | List available macOS sounds |

### Keyboard Shortcut

`Ctrl+Shift+.` - Test the current alert

## Beep Mode

The default mode is `beep` with Glass sound on macOS or a generated glass-like tone on other platforms.

| Platform | Sound |
|----------|-------|
| macOS | System sound (Glass by default) |
| Linux | Generated 1318Hz tone with harmonics |
| Windows | Generated 1318Hz tone with harmonics |

### Available macOS System Sounds

- **Glass** ✨ - Short, bright, bell-like (default)
- **Tink** - Soft, gentle, quiet
- **Pop** - Bubbly, quick burst
- **Basso** - Deep, bassy thump
- **Ping** - Crystal, ringing
- **Blow** - Soft whoosh
- **Bottle** - Lower version of Glass

## Song Notation

Notes are formatted as `NoteOctave:DurationMs`:

| Note | Frequency | Example |
|------|-----------|---------|
| C4 | 261.63 Hz | Middle C |
| E4 | 329.63 Hz |  |
| G4 | 392.00 Hz |  |
| C5 | 523.25 Hz | High C |
| E5 | 659.25 Hz |  |
| G5 | 783.99 Hz |  |
| A4 | 440.00 Hz | Concert A |

Examples:
- `C4:200` - Middle C for 200ms
- `C4:200,E4:200,G4:200,C5:400` - C major arpeggio
- `C5:150,C5:150,C5:150,G5:600` - Imperial March first phrase

## Keep Me Posted Skill

When the user asks to be kept updated, use the notification:

**Trigger phrases:**
- "keep me posted"
- "let me know when you're done"
- "notify me when complete"
- "alert me when finished"
- "ping me when done"
- "give me a heads up"

**What it does:**
1. Confirms notification will be sent
2. Completes the task
3. Plays the configured beep alert

## Settings File

Settings are stored in `~/.pi/pi-alerts-settings.json`:

```json
{
  "defaultMode": "beep",
  "beepCount": 1,
  "beepDelayMs": 200,
  "beepSound": "Glass",
  "toneSequence": [
    { "frequency": 523.25, "duration": 150 },
    { "frequency": 659.25, "duration": 150 },
    { "frequency": 783.99, "duration": 300 }
  ],
  "speechText": "Task complete!",
  "notificationTitle": "pi Alert",
  "volume": 80
}
```

## Platform Notes

### macOS
- Uses `afplay` for sound playback
- System sounds in `/System/Library/Sounds/`
- Uses `osascript` for notifications and `say` for speech

### Linux
- Uses `aplay`, `paplay`, or `play` for sound
- Uses `notify-send` for notifications
- Uses `espeak` or `espeak-ng` for speech
- Falls back to terminal bell

### Windows
- Uses PowerShell SoundPlayer for sound
- Uses Toast notifications
- Uses System.Speech for text-to-speech
- Falls back to console bell