pi-ping

Focus-aware notification and tab-marker extension for the pi coding agent. It alerts you only when a run finishes while you are working in another window.

Zero daemons, zero OS binaries, zero external dependencies. Pure ANSI terminal native.

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

Why pi-ping stands out

Most notification extensions either ping on every message, fire during auto-retries, or require OS-specific scripts (osascript, hyprctl, dunst). pi-ping does things the Unix way:

1. Zero OS dependencies: Uses native terminal escape sequences (DECSET 1004, OSC 9/99/777, OSC 0). Runs seamlessly across macOS, Linux, Windows, and tmux without helper daemons.
2. True focus detection: Intercepts in-stream terminal focus events (\x1b[I / \x1b[O). If you are already looking at the terminal, it stays completely silent.
3. Settled-state gating (agent_settled): Only pings when Pi is genuinely waiting on you — never interrupts mid-run during auto-retries, tool loops, or context compaction.
4. Noise-free:
   • Trivial turn filter: Skips short replies (<10s, 0 tools, 0 errors).
   • Away debounce (3s): Skips momentary glances or rapid window switching.
5. Append-only tab marker: Temporarily prepends [!] to the existing tab title while unwatched, and restores your title the moment you click back into the terminal.
6. Project-aware: Notification titles include the active directory name (e.g. Pi (my-project)).

How it works

1. You run a prompt in Pi:
   Tab title: "π - fix-auth - my-project"

2. You switch to your browser or editor while Pi works:
   Pi runs tools and edits code (24s).

3. The entire run finishes while you are away:
   Notification: "Pi (my-project): 3 tool calls, 24s"
   Tab title:    "[!] π - fix-auth - my-project"

4. You click back to the terminal:
   The tab title immediately restores:
   "π - fix-auth - my-project"

Comparison

Feature	Typical notification extensions	pi-ping
Looking at terminal	Pings anyway	Silent (native DECSET 1004 focus detection)
Momentary Alt-Tab	Immediate notification	Silent (>=3s continuous away debounce)
Quick 1-sentence reply	Pings anyway	Silent (<10s, 0 tools, 0 errors)
Auto-retries & Compaction	Pings on every intermediate step	Pings once after run fully settles (agent_settled)
Cancelled with Escape	Often triggers false alert	Silent
Tab status	Overwrites title permanently with emojis	Decorates title with [!] , clears on focus
Dependencies	Requires osascript, hyprctl, or Python	Zero dependencies (pure ANSI escape sequences)

Terminal support

Terminal	Focus detection	Notification	Tab title marker
Ghostty	Native (DECSET 1004)	OSC 9 / OSC 777	Supported out of the box (0ms instant unmark)
Kitty	Native (DECSET 1004)	OSC 99	Supported out of the box (0ms instant unmark)
WezTerm	Native (DECSET 1004)	OSC 9 / OSC 777	Supported out of the box (0ms instant unmark)
Ptyxis / GNOME Terminal / Console / VTE	Native (DECSET 1004)	notify-send	Supported out of the box (0ms instant unmark)
Alacritty	Native (DECSET 1004)	notify-send	Supported out of the box (0ms instant unmark)
iTerm2	Native (DECSET 1004)	OSC 9	Supported out of the box (0ms instant unmark)
Foot	Native (DECSET 1004)	OSC 777 / notify-send	Supported out of the box (0ms instant unmark)
Windows Terminal	Native (DECSET 1004)	OSC 9	Supported out of the box (0ms instant unmark)
Warp	Native (DECSET 1004)	OSC 9	Supported out of the box (0ms instant unmark)
tmux	#{window_focused} / DECSET 1004	Wrapped escape sequences	Supported out of the box (0ms instant unmark)
Linux (other)	Native / Fallback heuristic	notify-send	Supported out of the box (0ms instant unmark)

Installation

From npm:

pi install npm:@bukutsu/pi-ping

From GitHub:

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

Restart Pi or run /reload in your active session.

Commands

• /notify-check: Check active focus source, continuous away duration, turn stats, and whether a ping would fire.
• /notify-test: Send an immediate test notification to verify terminal and desktop alerts.

Configuration (optional)

• PI_PING_MARKER: Customize the tab marker prefix (default: [!] ).

  export PI_PING_MARKER="(!) "

Testing

bun run typecheck   # tsc --strict against the pi extension API
bun run test        # self-test: focus scanner and title-reply scanner