pi-ping

Focus-aware notifications and tab marker for the Pi coding agent.

pi-ping alerts you when a run finishes while you are in another window, and marks the terminal tab with [!] until you return. If you are already looking at the terminal, it stays quiet.

Repository: https://github.com/Bukutsu/pi-ping

Install

pi install npm:@bukutsu/pi-ping

Or from GitHub:

pi install git:github.com/Bukutsu/pi-ping

Restart Pi or run /reload in your active session.

What it does

• Notifies only when the terminal is unfocused.
• Adds [!] to Pi's tab title while a finished run is unread, and restores it when you return or type.
• Stays quiet on short turns (under 10s with no tools or errors) and cancelled runs.
• Waits 3 seconds after you switch windows before alerting so quick glances stay silent.
• Alerts once after the run fully settles (no pings during intermediate tool calls or auto-retries).
• Uses native terminal escapes (OSC 9, 99, 777) with notify-send fallback on Linux.

Terminal support

Works out of the box with terminals that support DECSET 1004 focus events (Ghostty, Kitty, WezTerm, Alacritty, iTerm2, Foot, Warp, Windows Terminal, and tmux).

Commands

• /notify-check: Check focus source, away time, and whether an alert would fire.
• /notify-test: Send an immediate test notification.

Configuration

Set PI_PING_MARKER to customize the tab title marker (default: [!] ):

export PI_PING_MARKER="(!) "

Development

bun install
bun run typecheck
bun test