pi-notify

Notification extension for pi coding agent — tab status, system sounds, terminal bell, and Bark push to iPhone.

中文版

---

Features

• Tab title + footer status — shows ⏳ running / ✅ complete / ❌ error on your terminal tab and footer
• System notification sound — plays a custom .wav / .mp3 / .aiff file when the agent finishes
• Loop mode — notification sound loops until you press any key or start a new interaction
• Terminal bell — optional BEL (\x07) on completion
• OSC 9 notification — desktop notification popup (iTerm2, Ghostty, WezTerm, Windows Terminal)
• Bark push — sends push notification to your iPhone via Bark
• Fully configurable — /notify interactive settings panel, all options are toggleable
• Sound preview — /notify-sound lets you browse and preview system sounds before selecting

Installation

# via git
pi install git:github.com/2008muyu/pi-notify

# or via npm (once published)
pi install npm:pi-notify

Then restart pi (or run :reload in pi).

Usage

/notify — Settings Panel

Opens an interactive settings panel with cursor persistence — toggles are applied inline without losing your place.

Option	Description
✅ Sound	Enable/disable notification sounds
✅ Terminal bell	Enable/disable BEL (\x07)
✅ Loop sound	Enable/disable looping notification sound
✅ OS notification	Enable/disable OSC 9 desktop notification
✅ Bark push	Set Bark device key for iPhone push
♪ Sound file	Pick a custom notification sound

Navigate with ↑↓, toggle with Enter, exit with Esc.

/notify-sound — Sound Picker

Browse and preview system sounds before selecting one as your notification sound.

• ↑↓ navigate list
• Space preview sound
• Enter select and save
• Esc cancel

Configuration

Configuration is stored in ~/.pi/agent/pi-notify.json. You can also use environment variables:

Variable	Default	Description
PI_NOTIFY_SOUND	true	Enable/disable sounds
PI_NOTIFY_BELL	true	Enable/disable terminal bell
PI_NOTIFY_LOOP	false	Enable/disable looping
PI_NOTIFY_OS_NOTIFY	true	Enable/disable OSC 9 notifications
BARK_KEY / PI_NOTIFY_BARK_KEY	—	Bark device key
BARK_SERVER	https://api.day.app	Bark server URL

How It Works

1. When the agent starts (agent_start), the extension sets the tab title to ⏳ and prepares for notifications
2. When the agent ends (agent_end), it triggers:
   • Terminal bell (optional)
   • OSC 9 desktop notification (optional)
   • System sound playback (custom file or system default)
   • Bark push to iPhone (if configured)
3. Loop mode: the sound keeps playing in a background PowerShell process. Press any key or start a new conversation to stop it
4. Error handling catches all failures silently — the extension never blocks the agent

Publishing to the pi Community

This package can be distributed through:

Via GitHub (recommended)

Users can install directly from GitHub:

pi install git:github.com/2008muyu/pi-notify

Via npm

To publish to npm and make it installable via pi install npm:pi-notify:

1. Ensure you have an npm account
2. Update package.json with the correct registry metadata
3. Run:

npm login
npm publish

Via the pi Package Registry

Check pi packages documentation for the official community registry once available.

---

License

MIT

---

中文说明

简介

pi-notify 是 pi 编程助手 的通知扩展，提供终端标签状态、系统提示音、响铃和 iPhone 推送功能。

功能

• 终端标签页 + 底部状态栏 — 显示 ⏳ 运行中 / ✅ 完成 / ❌ 错误
• 自定义提示音 — Agent 完成时播放自定义 .wav / .mp3 / .aiff 文件
• 循环模式 — 提示音持续循环，按任意键或开始新对话即停
• 终端响铃 — 可选的 BEL 提示音
• 桌面通知 — OSC 9 弹窗通知（iTerm2、Ghostty、WezTerm、Windows Terminal）
• Bark 推送 — 通过 Bark 推送到 iPhone
• 完全可配置 — /notify 交互式面板，所有选项即开即关
• 声音预览 — /notify-sound 浏览和试听系统音效

安装

# 通过 GitHub
pi install git:github.com/2008muyu/pi-notify

# 或通过 npm（发布后）
pi install npm:pi-notify

安装后重启 pi（或运行 :reload）。

使用方法

/notify — 设置面板

光标位置保持的交互式设置面板，开关项即时生效不跳转。

选项	说明
✅ Sound	启用/禁用提示音
✅ Terminal bell	启用/禁用终端响铃
✅ Loop sound	启用/禁用循环播放
✅ OS notification	启用/禁用桌面通知
✅ Bark push	设置 Bark 设备密钥
♪ Sound file	选择自定义提示音

↑↓ 导航，Enter 切换/进入，Esc 退出。

/notify-sound — 声音选择器

浏览和试听系统音效，选定后设为通知音。

• ↑↓ 浏览列表
• Space 试听
• Enter 选定并保存
• Esc 取消

配置

配置文件位于 ~/.pi/agent/pi-notify.json，也支持环境变量：

变量	默认值	说明
PI_NOTIFY_SOUND	true	启用/禁用声音
PI_NOTIFY_BELL	true	启用/禁用终端响铃
PI_NOTIFY_LOOP	false	启用/禁用循环
PI_NOTIFY_OS_NOTIFY	true	启用/禁用桌面通知
BARK_KEY / PI_NOTIFY_BARK_KEY	—	Bark 设备密钥
BARK_SERVER	https://api.day.app	Bark 服务器地址

工作原理

1. Agent 开始运行 → 标签页显示 ⏳
2. Agent 完成 → 触发：
   • 终端响铃（可选）
   • OSC 9 桌面通知（可选）
   • 播放提示音（自定义文件或系统默认）
   • Bark 推送（已配置时）
3. 循环模式：提示音在后台 PowerShell 进程中持续播放，按任意键或开始新对话即停止
4. 所有失败静默处理，绝不阻塞 Agent

发布到 pi 社区

通过 GitHub（推荐）

用户可以直接从 GitHub 安装：

pi install git:github.com/2008muyu/pi-notify

通过 npm

npm login
npm publish

然后用户可通过 pi install npm:pi-notify 安装。

通过 pi 官方包管理器

待官方社区注册中心上线后，可参考 pi packages 文档 发布。

---

许可证

MIT