@jmcombs/pi-notify

A Pi coding agent extension that sends a notification via your terminal emulator's native system (OSC 777/9/99) when Pi is idle or blocks on interactive input (e.g. ask_user) — so you can switch away while Pi works and get tapped on the shoulder the moment it needs you. Works in Ghostty, iTerm2, WezTerm, Kitty, etc. with zero OS binaries or dependencies.

Install

# Globally (recommended)
pi install npm:@jmcombs/pi-notify

# For a single session, without installing
pi -e npm:@jmcombs/pi-notify

What It Adds

• Event hook: agent_settled (one notification when Pi is idle) — sends a terminal notification via OSC, not a ping each time agent_end fires.
• Event hook: tool_execution_start — sends a notification when an interactive tool that blocks for your input starts. Defaults to ask_user (from pi-ask-user); while that prompt is open the agent is still running, so neither agent_end nor agent_settled fires.
• Command: /notify [message] — sends a one-shot test notification. Useful for verifying the extension is working after install. Defaults to "Waiting for your input" when called with no argument.

No tools are registered. The LLM does not call this extension directly.

Waiting-tool names

By default only ask_user triggers a mid-run “waiting for input” notification. Override with a comma-separated list:

# Watch additional interactive tools
export PI_NOTIFY_WAIT_TOOLS=ask_user,confirm

# Disable mid-run wait notifications (idle notification still fires)
export PI_NOTIFY_WAIT_TOOLS=

Terminal Support

Notifications are delivered using the terminal emulator's built-in OSC notification protocols (no OS daemons, no extra packages, no binaries). Supported terminals:

Unsupported (examples: Apple Terminal, Alacritty, base Windows console): the extension shows a message in the Pi TUI and recommends filing an issue at https://github.com/jmcombs/pi-extensions/issues.

No permissions dialogs or extra setup are required for most terminals. Desktop notification appearance (banners, sounds, persistence) is controlled entirely by your terminal emulator + OS notification center settings. Configure those in the terminal's preferences and/or macOS System Settings → Notifications. This extension emits no audio or OS notifications itself.

Ghostty on macOS

Ghostty enables OSC notifications by default (desktop-notifications = true). For the desktop notification to appear as a banner:

1. Permissions: System Settings → Notifications → Ghostty → Allow notifications. Set Alert Style to "Banners" (temporary) or "Alerts" (persistent).
2. (Optional) Config: Add to your Ghostty config if you had disabled it:

   desktop-notifications = true
   

   (Restart Ghostty or use ghostty +reload-config after changes.)
3. Testing: Run /notify Test Notification. Banners typically only appear when the Ghostty window is unfocused (background). When focused, check Notification Center; Ghostty may show a brief in-window indicator.

If no notification appears despite the above, the sequence was still written (successfully detected by the /notify command). Check Ghostty logs or file an issue.

Requirements

• Pi >= 0.72.0
• Node >= 22.19.0
• No API keys or additional configuration required

Development

This package lives in the pi-extensions monorepo.

# From the repo root
npm ci
npm run check       # full quality gate

# Try local changes against a real Pi session
pi -e ./packages/notify

The smoke test in index.test.ts verifies registration shape only — no OSC sequences or external calls are made during testing. Real end-to-end behaviour (terminal notifications) is exercised via pi -e.

License

MIT © Jeremy Combs