pi-chime

Terminal bell notification for Pi — chimes when the agent finishes responding. Detects your terminal emulator and uses the best available notification protocol, and sends a native macOS Notification Center banner when running on macOS.

Install

Global

pi install npm:pi-chime

Project-local

Writes to .pi/settings.json — portable across teams:

pi install -l npm:pi-chime

How It Works

Pi-chime hooks into agent_end and sends a notification when the agent loop finishes. It automatically detects which terminal you're running and picks the richest protocol that terminal supports. On macOS, it also triggers a Notification Center banner via osascript so you get a push-style alert even if the terminal's own OSC notification is subtle or suppressed.

Every chime ends with a BEL (\x07) character as a universal fallback.

Terminal Support

| Terminal | Native Protocol | macOS Banner | Fallback | | ------------------ | --------------- | ------------ | -------- | | Kitty | OSC 99 | Yes | BEL | | Ghostty | OSC 9 | Yes | BEL | | WezTerm | OSC 9 | Yes | BEL | | iTerm2 | OSC 9 | Yes | BEL | | Warp | OSC 777 | Yes | BEL | | macOS Terminal.app | — | Yes | BEL | | Unknown | OSC 777 | Yes (macOS) | BEL |

macOS Notification Permissions

If you don't see macOS Notification Center banners, your terminal app may not have permission to send notifications:

1. Open System Settings → Notifications
2. Find your terminal app (e.g., Ghostty, WezTerm, iTerm2, Warp, Terminal)
3. Ensure Allow Notifications is turned on
4. Set Alert style to Banners or Alerts

The banner is sent via osascript, which inherits the notification sandbox of the calling terminal process. If the terminal lacks permission, macOS silently drops the notification.

Commands

• /chime — open the chime settings menu where you can:
  • Test notification — trigger a notification with your current sound
  • Change sound — cycle through available notification sounds and preview them
  • Exit — close the menu

Sound Customization (macOS)

When running on macOS, you can customize the notification sound played by the osascript Notification Center banner. Use /chime → Change sound to select from the available options:

| Sound | Description | | ------- | ----------------- | | Purr | Soft and pleasant | | Glass | Clear timer-like | | Hero | Triumphant |

Your selection is saved to ~/.config/pi-chime/config.json and persists across sessions. The default sound is Purr.

You can also use any sound name from /System/Library/Sounds/ by editing the config file directly.

Behind the Scenes

See docs/protocols.md for a quick reference on the OSC escape sequences and protocols used behind the scenes.

Links

• Source
• Issues