pi-jobs-done-sound

A tiny Pi extension that plays a short sound when Pi finishes an agent turn and is ready for your next instruction.

Useful when you kick off a longer task, switch windows, and want an audible cue when the job is done.

Install from GitHub (quick)

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

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

Install from npm

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

Install

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 git:github.com/kmjayadeep/pi-jobs-done-sound

# Or from npm
pi -e npm:@kmjayadeep/pi-jobs-done-sound

Requirements

The extension includes extension/jobs_done.mp3 and tries these players:

• Linux: mpv, ffplay, mpg123, paplay, pw-play
• macOS: afplay

If no player works, it falls back to the terminal bell.

How it works

The extension listens for Pi's agent_end event and plays the bundled MP3:

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

Package structure

.
├── extension/
│   ├── index.ts
│   └── jobs_done.mp3
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

package.json declares this as a Pi package with:

{
  "keywords": ["pi-package", "pi-extension"],
  "pi": {
    "extensions": ["./extension"]
  }
}

Development

npm install
npm run typecheck
pi -e ./extension

Publishing

New versions are published to npm via a GitHub Actions workflow that uses OIDC for authentication and npm provenance — no stored secrets needed.

Prerequisites

Before the first publish, set up an npm publisher on npmjs.com:

1. Go to npm publishers page for your account.
2. Click "Add Publisher".
3. Enter your GitHub repository 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 repo.

Trigger a publish

Create and push a GitHub Release (with a tag like v0.1.0). The workflow at .github/workflows/publish.yml runs automatically:

# Tag and push
cd pi-jobs-done-sound
npm version patch    # bumps to 0.1.1, creates a git tag
git push --tags origin main

Then create a GitHub Release from the tag on the Releases page — this triggers the publish workflow.

Workflow details

• Uses npm publish --provenance with id-token: write for OIDC.
• Runs on release events (tag published) and can be triggered manually via the GitHub UI.
• Runs type checking before publishing.

License

MIT