# pi-agent-done-chime

Plays a pleasant chime when the [pi](https://pi.dev) 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](https://opengameart.org/content/pleasing-bell-sound-effect)
(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](./CREDITS.md) for full
attribution and license details.

## Install

From npm (recommended):

```bash
pi install npm:pi-agent-done-chime
```

From git:

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

Or try it once without installing:

```bash
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`:

```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](./LICENSE). The bundled sound is CC0 (public domain); see
[CREDITS.md](./CREDITS.md).