pi-agent-done-chime

Plays a pleasant chime when the pi coding agent settles after finishing work and is waiting for your input.

The chime is suppressed when you abort a run yourself (Esc) — you already know it stopped because you stopped it. It only rings when the agent genuinely finished and needs your attention.

Sound

Bundled CC0 sound: "Pleasing Bell" by Spring Spring, from OpenGameArt (license CC0 1.0 — public domain, no attribution required).

Amplified from the original (peak −24 dB) to peak −6 dB / mean −21 dB so it is clearly audible without being harsh. See CREDITS.md for full attribution and license details.

Install

From npm (recommended):

pi install npm:pi-agent-done-chime

From git:

pi install git:github.com/jlfwong/pi-agent-done-chime

Or try it once without installing:

pi -e npm:pi-agent-done-chime

After installing, reload with /reload (or restart pi). The chime is enabled by default.

Commands

| Command | Action | |---------|--------| | /chime | Toggle the chime on/off | | /chime on / /chime off | Set explicitly | | /chime test | Play the chime once | | /chime path | Print the bundled sound file path |

Config

The on/off state is persisted in ~/.pi/agent/pi-agent-done-chime.json:

{ "enabled": true }

It lives outside the package directory on purpose, so pi update and npm reinstalls don't wipe your preference.

You can also disable the whole extension via pi config.

How it works

Triggers on agent_settled — fires only when the agent is truly done and waiting for input (after retries, auto-compaction, and queued follow-ups drain). Fewer false dings than agent_end.

To skip your own aborts, the extension watches agent_end for the final assistant message's stopReason. pi sets it to "aborted" when a run is interrupted by the user, so the chime only plays when the agent settled after finishing real work.

Playback

• macOS (primary): afplay spawned detached so it never blocks the agent loop or holds the session open.
• Linux: paplay fallback.
• Windows: not supported by this extension yet.

License

MIT — see LICENSE. The bundled sound is CC0 (public domain); see CREDITS.md.