🔔 pi-jobs-done-sound

A tiny Pi extension that plays a sound notification when Pi finishes an agent turn.

Kick off a long-running task, switch windows, and get an audible cue when the job is done — no more staring at the terminal waiting.

---

✨ Features

• 🎵 Plays a completion sound when Pi emits the agent_end event
• 🖥️ Cross-platform — Linux (mpv, ffplay, mpg123, paplay, pw-play), macOS (afplay)
• 🛎️ Graceful fallback to the terminal bell if no audio player is found
• 📦 Self-contained — ships its own jobs_done.mp3
• 🪶 Zero configuration — install and forget

📦 Install

# From npm (recommended)
pi install npm:@kmjayadeep/pi-jobs-done-sound

# From GitHub
pi install git:github.com/kmjayadeep/pi-jobs-done-sound

Then restart Pi, or run /reload in an existing Pi session.

🧪 Try without installing

pi -e npm:@kmjayadeep/pi-jobs-done-sound

# Or from GitHub
pi -e git:github.com/kmjayadeep/pi-jobs-done-sound

🔧 Requirements

OS	Players tried (in order)
Linux	mpv, ffplay, mpg123, paplay, pw-play
macOS	afplay

If none are available, it falls back to the terminal bell (\x07).

🧠 How it works

pi.on("agent_end", async () => {
  // play jobs_done.mp3
});

That's it. The extension hooks into Pi's event system and plays the bundled MP3 whenever Pi finishes processing your request.

📁 Package structure

.
├── extension/
│   ├── index.ts          # Extension entry point
│   └── jobs_done.mp3     # Sound file
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

🛠️ Development

npm install
npm run typecheck
pi -e ./extension

📤 Publishing

New versions are published to npm via a GitHub Actions workflow using OIDC (no stored secrets!) with npm provenance.

One-time setup

1. Go to the npm publishers page for your account.
2. Click Add Publisher.
3. Enter your repo URL: https://github.com/kmjayadeep/pi-jobs-done-sound.
4. Confirm the OIDC connection.

This tells npm to trust OIDC tokens from GitHub Actions for this repository.

Trigger a publish

Create and push a GitHub Release with a version tag (e.g. v0.1.3):

npm version patch && git push --tags origin main

Then create a GitHub Release from the tag on the Releases page — the workflow fires automatically.

📄 License

MIT © Jayadeep KM