---
slug: "plentz-ding"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/plentz/ding@main/README.md"
repo: "https://github.com/plentz/ding"
source_file: "README.md"
branch: "main"
---
# 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 (or runs `say` when configured) 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/speech. With [`alerter`](https://github.com/vjeantet/alerter) installed, clicking the notification body focuses the originating terminal/app; clicking the close/dismiss control does not focus it.

## Install

From npm:

```bash
pi install git:github.com/plentz/ding
```

## Optional dependency

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

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

```text
/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.

```text
finish the task and notify me with /ding
finish the task /ding I'm done, master
```

## Settings

Configure ding with JSON settings. Global settings live at:

```text
~/.pi/agent/ding.json
```

Project-local settings can live at:

```text
.pi/ding.json
```

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

Example:

```json
{
  "autoNotify": false,
  "sound": "Glass",
  "say": "I'm done, master",
  "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. Ignored when `say` is set. |
| `say`               | unset             | Phrase to speak with the macOS `say` command instead of playing a sound. Set to a non-empty string such as `"I'm done, master"`. |
| `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.                                                                                                                                                                                                    |