pi-nudge

Native terminal notifications for pi.

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:

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:

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