🔔 pi-smart-voice-notify

Windows-optimized smart notification extension for the Pi coding agent.

pi-smart-voice-notify monitors Pi session and tool events to alert you via multi-engine TTS, sound playback, desktop toast notifications, and optional webhook/AI-assisted messaging when the agent requires your attention.

Features

• Multi-channel notifications

  • Sound – local sound playback with fallback beeps and reusable reminder playback control
  • Voice – auto-selectable TTS engines: Edge, espeak-ng, ElevenLabs, OpenAI-compatible, and Windows SAPI
  • Desktop toasts – cross-platform notifications via node-notifier (Windows/macOS/Linux)
  • Webhook delivery – optional Discord or generic HTTP webhook notifications

• Intelligent event detection

  • Task completion (idle)
  • Authoritative permission-system wait events plus current-session forwarded subagent permission requests
  • Questions requiring input (when custom question tool is loaded)
  • Errors

• Reminder system

  • Configurable per-event reminder delays with follow-up scheduling
  • Exponential backoff multiplier for follow-ups
  • Auto-cancel reminders on user activity or resolution

• Focus and wake handling

  • Wakes display from sleep before notifications
  • Optional focused-terminal suppression on Linux
  • Cross-platform wake strategies for Windows, macOS, and Linux sessions

• Sound customization

  • Direct per-event sound files
  • Theme-based sound selection and optional per-project sound discovery
  • Theme randomization and default volume controls

• AI message generation

  • Optional AI-generated notification text with caching and template fallback

• Interactive settings UI

  • /voice-notify command opens a modal for live configuration
  • Settings persist to disk automatically

• Debug logging

  • Optional JSONL debug output for troubleshooting

Installation

Local Extension Folder

Place this folder in either location (Pi auto-discovers both):

• Global default: ~/.pi/agent/extensions/pi-smart-voice-notify (respects PI_CODING_AGENT_DIR)
• Project: .pi/extensions/pi-smart-voice-notify

As an npm Package

pi install npm:pi-smart-voice-notify

From Git

pi install git:github.com/MasuRii/pi-smart-voice-notify

Usage

Commands

Command	Description
/voice-notify	Opens the settings modal (interactive mode) or prints config summary
/voice-notify status	Displays current configuration and question tool availability
/voice-notify reload	Reloads config from disk and resets reminder state
/voice-notify on	Enables the extension
/voice-notify off	Disables the extension
/voice-notify test [type]	Triggers a test notification (bypasses throttling)

Test types: idle, permission, question, error

Example

/voice-notify test idle
/voice-notify test permission

Configuration

Configuration is stored at:

Default global path: ~/.pi/agent/extensions/pi-smart-voice-notify/config.json
Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-smart-voice-notify/config.json when PI_CODING_AGENT_DIR is set

A starter template is provided in config/config.example.json. On startup, the extension creates config.json with defaults if missing.

Configuration Options

Option	Type	Default	Description
enabled	boolean	true	Master on/off switch
windowsOptimized	boolean	true	Show a compatibility notice on platforms other than Windows/Linux
notificationMode	string	"sound-first"	Mode: sound-first, tts-first, both, sound-only
enableSound	boolean	true	Enable sound playback
enableTts	boolean	true	Enable text-to-speech delivery
ttsEngine	string	"auto"	Engine: auto, edge, espeak-ng, elevenlabs, openai, sapi
enableDesktopNotification	boolean	true	Enable desktop toast notifications
desktopNotificationTimeout	number	8	Toast display duration in seconds (1–60)
wakeMonitor	boolean	true	Wake display from sleep before notifying
idleThresholdSeconds	number	30	System idle threshold before waking monitor (5–600)
skipWhenFocused	boolean	false	Suppress notifications while the active Linux terminal/editor is focused

windowsOptimized keeps compatibility messaging for platforms that do not have Linux/Windows-native behavior. Linux users no longer see this notice.

Event Toggles

Option	Type	Default	Description
enableIdleNotification	boolean	true	Notify when agent finishes a task
enablePermissionNotification	boolean	true	Notify when the permission system reports requests waiting for approval
enableForwardedPermissionWatcher	boolean	true	Watch current-session forwarded permission request/response files and notify when new requests arrive
includeForwardedPermissionAgentName	boolean	true	Include sanitized requester agent name in forwarded permission notification text
watchLegacyForwardedPermissionPath	boolean	true	Retained for config compatibility; unscoped legacy forwarded-permission paths are ignored because they cannot prove the current target session
enableQuestionNotification	boolean	true	Notify when agent asks a question*
enableErrorNotification	boolean	true	Notify on errors
suppressIdleAfterError	boolean	true	Skip idle notification if turn had errors

*Question notifications only work when a custom question tool is loaded.

Forwarded permission watcher notifications use privacy-safe text, require the request targetSessionId to match the active Pi session, and never include raw forwarded message content.

Reminder Settings

Option	Type	Default	Description
reminderEnabled	boolean	true	Enable reminder notifications
reminderDelaySeconds	number	30	Initial delay before first reminder (5–300)
followUpEnabled	boolean	true	Enable follow-up reminders
maxFollowUps	number	3	Maximum follow-up count (1–10)
followUpBackoffMultiplier	number	1.5	Delay multiplier for each follow-up

TTS Settings

Option	Type	Default	Description
voice	string	"Microsoft Zira Desktop"	Generic preferred voice label
rate	number	-1	Generic speaking rate
volume	number	85	Preferred playback volume percentage
fallbackChain	array	["edge", "espeak-ng", "sapi"]	TTS engines tried when ttsEngine is auto
ttsVoice	string	"Microsoft Zira Desktop"	Legacy SAPI-compatible alias
ttsRate	number	-1	Legacy SAPI-compatible alias
edgeVoice	string	"en-US-JennyNeural"	Microsoft Edge voice
espeakVoice	string	"en"	espeak-ng voice for Linux fallback
elevenLabsVoiceId	string	"cgSgspJ2msm6clMCkdW9"	ElevenLabs voice id
openaiTtsVoice	string	"alloy"	OpenAI-compatible voice

Sound File Paths

Option	Type	Default
idleSoundFile	string	"assets/soft-notification.mp3"
permissionSoundFile	string	"assets/attention-alert.mp3"
questionSoundFile	string	"assets/attention-alert.mp3"
errorSoundFile	string	"assets/attention-alert.mp3"

Paths can be absolute or relative to the extension directory.

Sound, Webhook, and AI Settings

Option	Type	Default	Description
themeName	string	"default"	Preferred sound theme name
enablePerProjectSounds	boolean	false	Search the current project for matching notification sounds
randomizeThemeSounds	boolean	true	Randomize among matching themed sounds
webhook.enabled	boolean	false	Enable Discord/generic webhook delivery
webhook.events	array	["idle", "permission", "question", "error"]	Notification types sent through webhooks
aiMessages.enabled	boolean	false	Enable AI-generated notification copy
aiMessages.model	string	"llama3"	Model id used for AI notification generation
aiMessages.caching.enabled	boolean	true	Cache generated messages to reduce repeat calls
minNotificationIntervalMs	number	1500	Throttle interval between same-type notifications
debugLog	boolean	false	Enable debug logging to file

Notification Modes

Mode	Behavior
sound-first	Play sound first; fall back to TTS on failure
tts-first	Speak TTS first; fall back to sound on failure
both	Play sound and speak TTS simultaneously
sound-only	Play sound only, no TTS or reminders

Troubleshooting

Settings modal doesn't appear

The modal requires interactive UI mode (ctx.hasUI). In non-interactive contexts, /voice-notify prints a config summary instead.

Desktop notifications not showing

1. Ensure enableDesktopNotification is true
2. Check that node-notifier is installed
3. Enable debugLog and check debug/pi-smart-voice-notify.log for desktop.notify.failed events

No sound or voice on Windows

1. Sound and TTS are Windows-only (process.platform === "win32")
2. The extension uses PowerShell for audio playback and SAPI—ensure PowerShell is available
3. Enable debugLog and search for powershell.exec entries

Question notifications never trigger

Question notifications require a custom question tool to be loaded. Run /voice-notify status to verify questionToolAvailable=true.

Wake monitor not working

• Windows: Uses SendKeys (F15) via PowerShell
• macOS: Uses caffeinate -u -t 1
• Linux: Uses xset dpms force on or GNOME D-Bus

Ensure system idle time exceeds idleThresholdSeconds for wake to trigger.

Technical Details

Architecture

index.ts                    → Extension entrypoint (re-exports src/index.ts)
src/
├── index.ts                → Main extension logic, event handlers, command registration
├── config-store.ts         → Config paths, normalization, env overrides, load/save utilities
├── types.ts                → Shared configuration and runtime types
├── notify-audio.ts         → Audio dispatch and Windows/SAPI playback integration
├── tts.ts                  → Multi-engine TTS selection and speech dispatch
├── desktop-notify.ts       → Desktop toast notifications via node-notifier
├── permission-forwarding-watcher.ts → Watches forwarded permission request directories
├── reminder-playback.ts    → Deduplicates/cancels overlapping reminder playback
├── sound-theme.ts          → Theme and sound file resolution
├── per-project-sound.ts    → Project-local sound discovery helpers
├── webhook.ts              → Discord and generic HTTP webhook delivery
├── ai-messages.ts          → AI-generated notification message generation and caching
├── linux.ts                → Linux wake/audio/focus helpers
├── focus-detect.ts         → Terminal focus detection cache
├── logging.ts              → Debug logger with JSONL output
└── zellij-modal.ts         → Settings modal UI components

Event Hooks

Event	Behavior
session_start	Load config, reset state, update status bar. Handles all session lifecycle transitions via reason (startup, reload, new, resume, fork).
session_shutdown	Cancel reminders, clear status
input	Track user activity, cancel pending reminders
agent_start	Reset error tracking
tool_call	Detect permission blocks
tool_result	Classify results (question/permission/error)
agent_end	Trigger idle notification (if enabled)

Debug Logging

When debugLog: true, JSONL events are written to:

Default global debug log path: ~/.pi/agent/extensions/pi-smart-voice-notify/debug/pi-smart-voice-notify.log (respects PI_CODING_AGENT_DIR)

Events include: config changes, notifications triggered, audio dispatch, reminders, and errors.

Development

npm install
npm run build      # TypeScript compilation
npm run lint       # Alias for build
npm run test       # Node test runner with built-in TypeScript stripping
npm run check      # build + test

Requirements: Node.js ≥ 24

Related Pi Extensions

• pi-tool-display — Compact tool rendering and diff visualization
• pi-permission-system — Permission enforcement for tool and command access
• pi-MUST-have-extension — RFC 2119 keyword normalization for prompts
• pi-startup-redraw-fix — Fix terminal redraw glitches on startup

License

MIT