pi-sound-noti

Sound notifications for the Pi coding agent — and its fork oh-my-pi (omp). Know what your agent is doing without watching the terminal:

| Cue | When it plays | | --- | --- | | question | An ask-like tool (ask, ask_user_question, …) starts waiting for your answer, a tool approval or plan approval prompt opens (omp), or the agent finishes its turn with a plain-text question | | done | The agent run fully settles and the session is really idle — never on intermediate turn ends while queued prompts remain | | error | The final assistant message ended with stopReason: "error" (provider/API failure). User-initiated aborts stay silent |

One package, two runtimes, no configuration: the extension detects the ambient event surface at registration time. Stock pi resolves completion via agent_settled; omp resolves it via session_stop plus tool-approval and plan-proposal cues. Handlers for events a runtime never emits simply stay dormant — nothing breaks on either side.

Built-in OS audio backends, no dependencies:

• macOS — afplay
• Linux — pw-play → paplay → canberra-gtk-play (freedesktop sound theme)
• Windows — PowerShell System.Media (custom .wav files or system sounds)

Install

On pi:

pi install npm:pi-sound-noti
# or straight from git
pi install git:github.com/noizbuster/pi-sound-noti

On oh-my-pi (omp):

omp install pi-sound-noti
# or link a checkout
omp install ./pi-sound-noti

Then restart the agent and verify all three cues:

/sound-test question
/sound-test done
/sound-test error

How it works

• Immediate question cues fire on tool_execution_start for ask-like tool names — on omp also on tool_approval_requested and on a successful plan proposal (write → xd://propose) — guarded to interactive TUI sessions and rate-limited by a cooldown.
• Completion cues fire only when the session is really done:
  • pi: on agent_settled, which is emitted only after automatic retries, compaction, and queued continuations are exhausted.
  • omp: on session_stop, after re-checking that no queued follow-up picked up the session.
• The final assistant message (captured on agent_end, or read from omp's session_stop payload) is classified by stopReason:
  • "error" → error cue (even while a plan approval is pending)
  • "aborted" → silence (you cancelled it)
  • reply ending in ? → question cue (fallback, can be disabled)
  • anything else → done cue
• While an omp plan approval is pending, the completion cue stays suppressed — the question cue already played when the approval UI opened. The flag resets on your next input.
• hasPendingMessages()/isIdle() are re-checked after a short quiet window so queued follow-ups never trigger a premature done cue.

Configuration

All configuration is via environment variables — no settings file changes needed.

| Variable | Default | Description | | --- | --- | --- | | PI_SOUND_NOTIFY | on | Set off, 0, or false to mute without uninstalling | | PI_SOUND_QUESTION | (system sound) | Custom sound file played for the question cue | | PI_SOUND_DONE | (system sound) | Custom sound file played for the done cue | | PI_SOUND_ERROR | (system sound) | Custom sound file played for the error cue | | PI_SOUND_ASK_TOOLS | (see below) | Comma-separated extra tool names that trigger the question cue | | PI_SOUND_PLAIN_QUESTION | on | Set off to disable the plain-text ? question fallback | | PI_SOUND_COOLDOWN_MS | 300 | Minimum gap between question cues | | PI_SOUND_ALL_MODES | off | Set 1 to also play in non-TUI UI modes (e.g. rpc) |

Ask-like tools recognized by default: ask, ask_user, ask_user_question, ask-user-question. Extend the list for custom question tools:

export PI_SOUND_ASK_TOOLS="my_question_tool,confirm_dialog"

Example with custom sounds:

export PI_SOUND_QUESTION="$HOME/.sounds/ding.wav"
export PI_SOUND_DONE="$HOME/.sounds/success.wav"
export PI_SOUND_ERROR="$HOME/.sounds/failure.wav"

On Linux the custom file is played with pw-play/paplay, so any format your PulseAudio/PipeWire stack handles works (.oga, .wav, .flac, …). On Windows, custom files must be .wav.

License

MIT