zed-notify

A pi extension that emits a terminal BEL (\x07) when pi finishes a turn, so Zed Terminal Threads can show a visual completion notification.

What it does

zed-notify listens to pi's agent_end event and writes a single terminal bell character:

pi.on("agent_end", async () => {
  process.stdout.write("\x07");
});

This package is intentionally minimal. It does not use OSC 9, system notifications, or sound hooks. It relies on Zed Terminal Threads handling BEL.

Install

From npm

pi install npm:zed-notify

From GitHub

pi install git:github.com/ssdiwu/zed-notify

Try once

pi --no-session -e /absolute/path/to/zed-notify -p "reply once: test"

Install as a local/global pi package

pi install /absolute/path/to/zed-notify

**不要把 index.ts 拷贝到 ~/.pi/agent/extensions/zed-notify/**作为单源加载方式。pi 的扩展扫描是 包列表 + 自动发现目录 双轨，手挂副本会与已注册的包形成「双源漂移」，同一 agent_end 事件会被两个 handler 各发一次 \x07。详见 AGENTS.md「分发与加载约定（v0.0.2 起）」一节。

Required Zed configuration

This extension is designed for Zed Agent Panel → Terminal Thread.

Add these settings to ~/.config/zed/settings.json:

{
  "agent": {
    "notify_when_agent_waiting": "primary_screen",
    "play_sound_when_agent_done": "never"
  },
  "terminal": {
    "bell": "system"
  }
}

Setting meanings

• agent.notify_when_agent_waiting
  • "primary_screen": show the visual notification on the primary screen
  • "all_screens": show the visual notification on all screens
  • "never": disable the visual notification
• agent.play_sound_when_agent_done
  • "never": silent notification
  • "when_hidden": only play sound when the panel/thread is hidden
  • "always": always play sound
• terminal.bell = "system"
  • lets Zed react to BEL (\x07)

Important behavior notes

• Works for Zed Terminal Threads.
• Zed's visual notification is intended for the not-in-focus case. If the terminal thread is already focused, Zed may not show the visual pop-up.
• This package follows the same bell-based path that works well for terminal-first agent workflows in Zed.
• This package does not depend on OSC 9. Zed currently ignores OSC 9 terminal notifications.

Verify your Zed setup first

In a Zed Terminal Thread, run:

printf '\a'

If Zed reacts, the bell path is working. Then test zed-notify:

pi --no-session -e /absolute/path/to/zed-notify -p "reply once: test"

Development

tsc --noEmit

Changelog

See CHANGELOG.md.

License

MIT