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