# pi-nudge

Native terminal notifications for [pi](https://github.com/badlogic/pi-mono).

When pi finishes a turn, pi-nudge sends a native terminal notification.

## Install

```
pi install pi-nudge
```

## Notes

Supported terminals for notifications:
- **Ghostty**, **iTerm2** (OSC 9)
- **Kitty** (OSC 99)
- **WezTerm**, **rxvt-unicode** (OSC 777)
- **tmux** (passthrough wrapper)

Ghostty appears to have its own focus awareness: in testing, it did not show a notification when the notification was sent from the currently focused tab. We couldn't find documentation for that behavior, so treat it as an observed detail rather than a documented guarantee.

There is also optional support for `ctx.ui.isTerminalFocused()`, but that method came from a private pi fork we were testing against and is not required when using Ghostty.

Without `isTerminalFocused()`, pi-nudge still sends notifications normally. On Ghostty, the terminal itself may already suppress notifications from the focused tab.

## Inter-extension API

Other extensions can trigger notifications via the shared event bus:

```typescript
pi.events.emit("nudge", { title: "Pi", body: "Needs your approval" });
```

If `ctx.ui.isTerminalFocused()` is available, `pi-nudge` will use it for these event-driven notifications too.

An emitting extension can still check focus itself if it wants to avoid emitting the event in the first place:

```typescript
if (!ctx.ui.isTerminalFocused?.()) {
  pi.events.emit("nudge", { title: "Pi", body: "Needs your approval" });
}
```

That method is not part of stock pi, and Ghostty users may not need it.

## License

MIT