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

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

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

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

{
  "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