@heathhe/pi-agent-notify

Pi extension that sends host terminal or desktop notifications when an agent run finishes or fails.

English | 简体中文

Features

• Sends one notification on agent_end
• Shows Pi done for successful runs
• Shows Pi failed when the final assistant message has errorMessage or a non-success stopReason
• Includes project name, duration, and model when available
• Prefers host terminal-owned notifications, then falls back to platform native notification when available
• Maps Zap, WezTerm, Ghostty, Kitty, iTerm2, Terminal.app, and compatible terminals to their best notification protocol
• Supports OSC 777, OSC 99, OSC 9, Linux notify-send, Windows PowerShell Toast, and bell fallback

Install

Install from npm:

pi install npm:@heathhe/pi-agent-notify

Install a specific version:

pi install npm:@heathhe/[email protected]

After installing, restart Pi or run:

/reload

For local development:

git clone [email protected]:Heath-Jian/pi-agent-notify.git
cd pi-agent-notify
pi install .

Usage

The extension runs automatically. When a Pi agent run ends, it sends a success or failure notification.

The only command exposed by the extension is:

/notify-doctor

Use it to inspect the detected host terminal and notification backend.

Notification Routing

The default auto mode tries notification backends in this order:

terminal protocol -> native/system when available -> bell

Protocol mapping:

| Terminal | Protocol | | --- | --- | | Zap | OSC 777 | | WezTerm | OSC 777 | | Ghostty | OSC 777 | | rxvt/urxvt/Terminology-compatible terminals | OSC 777 | | Kitty | OSC 99 | | iTerm2 | OSC 9 | | Terminal.app | OSC 9 | | Unknown terminal | Linux/Windows native fallback, otherwise bell |

In Zap, this uses Zap's OSC notification support, so the notification can be owned by Zap. If Zap is frontmost, Zap may show an in-window toast instead of a macOS banner even when macOS notification permission is enabled. When Zap is in the background, Zap decides whether its terminal-owned notification is promoted to a system banner.

Configuration

Environment variables:

| Name | Default | Description | | --- | --- | --- | | PI_AGENT_NOTIFY_DISABLE | 0 | Set to 1 to disable notifications. | | PI_AGENT_NOTIFY_METHOD | auto | One of auto, system, native, terminal, notify-send, powershell, osc777, osc99, osc9, bell. | | PI_AGENT_NOTIFY_FORCE_METHOD | unset | Legacy alias for PI_AGENT_NOTIFY_METHOD. | | PI_AGENT_NOTIFY_TERMINAL_PROTOCOL | auto | One of auto, osc777, osc99, osc9, all, or aliases such as zap, wezterm, ghostty, kitty, iterm2, terminal. | | PI_AGENT_NOTIFY_TOOL_ERRORS | 0 | Set to 1 to mark any tool execution error as a failed run. |

By default, tool errors do not mark the whole run as failed. Pi agents can often recover from a failed shell command or file operation and still finish successfully. Set PI_AGENT_NOTIFY_TOOL_ERRORS=1 if you prefer stricter behavior.

License

MIT

简体中文

pi-agent-notify 是一个 Pi 扩展：当 Pi agent 执行完成或失败时，向宿主终端或系统桌面发送通知。

功能特性

• 在 agent_end 时发送一条通知
• 成功时显示 Pi done
• 失败时显示 Pi failed
• 通知内容包含项目名、耗时、模型信息
• 优先使用宿主终端自己的通知协议，再 fallback 到平台原生通知能力
• 自动匹配 Zap、WezTerm、Ghostty、Kitty、iTerm2、Terminal.app 等终端的最佳通知协议
• 支持 OSC 777、OSC 99、OSC 9、Linux notify-send、Windows PowerShell Toast 和 bell fallback

安装

从 npm 安装：

pi install npm:@heathhe/pi-agent-notify

安装指定版本：

pi install npm:@heathhe/[email protected]

安装后重启 Pi，或者在 Pi 内执行：

/reload

本地开发安装：

git clone [email protected]:Heath-Jian/pi-agent-notify.git
cd pi-agent-notify
pi install .

使用方式

扩展会自动运行。每次 Pi agent 执行结束后，它会根据成功或失败状态发送通知。

扩展只暴露一个诊断命令：

/notify-doctor

它可以查看当前识别到的宿主终端和通知后端等信息。

通知路由

默认 auto 模式按下面顺序尝试：

terminal protocol -> native/system when available -> bell

协议映射：

| 终端 | 协议 | | --- | --- | | Zap | OSC 777 | | WezTerm | OSC 777 | | Ghostty | OSC 777 | | rxvt/urxvt/Terminology 兼容终端 | OSC 777 | | Kitty | OSC 99 | | iTerm2 | OSC 9 | | Terminal.app | OSC 9 | | 未识别终端 | Linux/Windows 原生 fallback，否则 bell |

在 Zap 中，这会使用 Zap 的 OSC 通知能力，因此通知可以归属于 Zap。如果 Zap 当前在前台，Zap 可能显示窗口内 toast，而不是 macOS 系统横幅；当 Zap 在后台时，是否提升为系统横幅由 Zap 自己决定。

配置

环境变量：

| 名称 | 默认值 | 说明 | | --- | --- | --- | | PI_AGENT_NOTIFY_DISABLE | 0 | 设置为 1 可关闭通知。 | | PI_AGENT_NOTIFY_METHOD | auto | 可选：auto、system、native、terminal、notify-send、powershell、osc777、osc99、osc9、bell。 | | PI_AGENT_NOTIFY_FORCE_METHOD | unset | PI_AGENT_NOTIFY_METHOD 的旧别名。 | | PI_AGENT_NOTIFY_TERMINAL_PROTOCOL | auto | 可选：auto、osc777、osc99、osc9、all，或 zap、wezterm、ghostty、kitty、iterm2、terminal 等别名。 | | PI_AGENT_NOTIFY_TOOL_ERRORS | 0 | 设置为 1 后，任意工具执行错误都会被视为失败。 |

默认情况下，工具错误不会直接把整轮 agent 运行标记为失败，因为 agent 经常可以从一次 shell 或文件操作失败中恢复，并最终成功完成任务。如果你希望更严格，可以设置 PI_AGENT_NOTIFY_TOOL_ERRORS=1。

许可证

MIT