zed-notify

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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:

```ts
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

```bash
pi install npm:zed-notify
```

### From GitHub

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

### Try once

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

### Install as a local/global pi package

```bash
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`:

```jsonc
{
  "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:

```bash
printf '\a'
```

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

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

## Development

```bash
tsc --noEmit
```

## Changelog

See `CHANGELOG.md`.

## License

MIT

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