ding

A Pi package that provides the ding extension: a small macOS task-ready notification helper for coding agents.

The extension automatically runs after each Pi agent task settles, using the last user prompt as the notification body. It plays a ding sound and, when appropriate, shows a macOS Notification Center banner. If the originating Apple Terminal tab is already focused, it skips the banner and only plays the sound. With alerter installed, clicking the notification body focuses the originating terminal/app; clicking the close/dismiss control does not focus it.

Install

From npm:

pi install npm:@plentz/ding

From a local checkout:

pi install /absolute/path/to/pi-ding

Optional dependency

For click-to-focus behavior on Notification Center banners, install alerter:

brew install vjeantet/tap/alerter

Without alerter, the extension falls back to AppleScript notifications and sound.

Usage

After installation, Pi loads the extension automatically. When an agent task finishes and Pi is ready for input again, the extension sends a ding notification using the last user prompt as the summary.

You can also send a manual notification with the bundled Pi command:

/ding Optional notification summary

If autoNotify is disabled and you want a notification for a single agent task, include /ding anywhere in the prompt. Text after /ding becomes the notification summary; if nothing follows it, ding uses the task prompt as the summary.

finish the task and notify me with /ding
finish the task /ding Task is ready

Settings

Configure ding with JSON settings. Global settings live at:

~/.pi/agent/ding.json

Project-local settings can live at:

.pi/ding.json

Project-local settings are only read for trusted projects and override global settings.

Example:

{
  "autoNotify": false,
  "sound": "Glass",
  "notifyWhenFocused": false,
  "focusOnClick": true,
  "activateBundleId": "com.apple.Terminal",
  "title": "AI task ready"
}

Settings:

| Key | Default | Description | | ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | autoNotify | true | Automatically ding when an agent task settles. Set to false to keep only manual /ding. | | sound | "Glass" | Sound to play: a macOS system sound name with or without .aiff, an absolute/~/ path to an afplay-compatible audio file such as "~/Sounds/done.mp3", true for the default sound, or false to disable sound. | | notifyWhenFocused | false | Show a banner even when the originating Apple Terminal tab is focused. | | focusOnClick | true | Focus the originating terminal/app when the notification body is clicked. Close/dismiss still does not focus. | | activateBundleId | unset | Override the app bundle ID used for click-to-focus. | | title | "AI task ready" | Notification title. |