pi-notify

个人习惯 ssh -> tmux -> pi 的方式
因此通过该插件用 桌面通知、可选的 tmux 窗口标记或 JSON webhook 等方式进行及时提醒。

理论上兼容本地、非tmux的环境。

通知内容

Pi 等待输入

项目：pi-notify
主机：dev-server
位置：work / 窗口 2 / 分屏 1

上图按字段分行展示；OSC 桌面通道会把正文合并为一行，webhook 则把标题和正文渲染到用户配置的 JSON 模板中。默认不显示内部 ID、完整路径或提示内容。通知字段与传输原理 →

安装

当前验证基线：Pi 0.86.0、Node 24.20.0；tmux 集成测试基线为 3.5a。

从 npm 安装用户级 Pi 包：

pi install npm:@lumintian/pi-notify

如果要把依赖写入当前项目的 .pi/settings.json，使用：

pi install -l npm:@lumintian/pi-notify

安装后启动 Pi；如果 Pi 已在运行，执行 /reload，再运行 /pi-notify status。Pi 通过包清单只加载 extensions/pi-notify.ts；该文件是公开入口，src/ 保存实现。Pi 可直接加载发布包中的 TypeScript，因此无需自行编译或安装开发依赖。

只想在当前运行中临时试用、不写入设置时，可以执行：

pi -e npm:@lumintian/pi-notify

更新已安装的 npm 包：

pi update npm:@lumintian/pi-notify

快速验证

默认启用 bell 与 OSC 777，webhook 默认关闭。

/pi-notify status
/pi-notify test terminal    # 测试桌面通知
/pi-notify test bell        # 测试 tmux bell
/pi-notify test webhook     # 测试已配置并启用的 webhook

不使用 tmux

可以直接从本地终端或 SSH 远程 shell 的交互式 TTY 启动 Pi。此时 terminal 通道将 OSC 777 直接写到当前终端，webhook 也照常工作；只有 tmux BEL/窗口标记会以 outside-tmux 跳过，通知中不显示 tmux 位置。

桌面通知最终由运行 SSH 客户端或 Pi 的本地终端显示，因此该终端需要支持 OSC 777，例如 WezTerm 或 Ghostty，并允许系统通知。Pi 还必须以 TUI 模式运行，且标准输出必须是 TTY。没有终端接收控制序列时 terminal 通道无法显示通知；webhook 的 HTTP 发送链路不依赖终端，但 Pi 进程必须仍在运行。

若在 tmux 后台窗口工作，用户 tmux 配置通常需要：

set -g allow-passthrough all
setw -g monitor-bell on

all 允许不可见 pane 中的程序向本地终端透传控制序列，仅对可信程序启用。插件不会自动应用这些设置。written 只表示写出了控制序列，不是桌面显示回执。排错与限制 →

配置

可选用户配置默认为 ~/.pi/agent/extensions/pi-notify.json，不读取项目级配置。完整示例见 config.example.json。

{
  "content": {
    "cwd": "basename",
    "promptTitle": false,
    "details": false
  }
}

details: true 会附加带标签的 tmux 内部 ID 和 Pi 会话短 ID。示例配置使用 ntfy 演示通用 webhook 的 URL、请求头环境变量与 JSON 模板。修改配置后 /reload。完整配置与 webhook 设置 →

开发

pnpm install --frozen-lockfile
pnpm check

使用 package.json 固定的 pnpm 12.5.1。check 包含类型检查、测试、真实发布包及 Pi 加载检查。tmux/PTY 测试需要 tmux 和 Python 3；缺少时明确跳过，不视为已验证。源码结构、测试与发布 →

卸载

用户级安装：

pi remove npm:@lumintian/pi-notify

项目级安装：

pi remove -l npm:@lumintian/pi-notify

如果 Pi 已在运行，随后执行 /reload。用户配置可保留，无需恢复 tmux 名称或主题。

许可证

本项目采用 MIT License，版权所有 © 2026 Lumintian。