@bukutsu/pi-ping

Focus-aware notification and tab-marker extension for the Pi coding agent. Sends native terminal notifications and marks window titles only when unfocused on real work.

Packages

Package details

extension

Install @bukutsu/pi-ping from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@bukutsu/pi-ping
Package
@bukutsu/pi-ping
Version
1.2.4
Published
Sep 22, 2026
Downloads
116/mo · 26/wk
Author
bukutsu
License
MIT
Types
extension
Size
21 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

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