# 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