pi-macos-notify

Minimal Pi extension for macOS notifications. It uses osascript.

Install

pi install npm:@npm-ken/pi-macos-notify

Or test from this checkout:

pi -e ./extensions/macos-notify.ts

Publish

bun pm pack --dry-run
bun publish --access public

Configure

On first load, the extension creates:

~/.pi/agent/extensions/pi-macos-notify/macos-notify.toml

Project override, only used after project trust:

cp macos-notify.toml.example .pi/macos-notify.toml

Custom path, loaded after the default and project override:

PI_MACOS_NOTIFY_CONFIG=/path/to/macos-notify.toml pi

Defaults notify on agent_settled and user_question. Set tool_error = true to include short tool error payloads when Pi provides them. user_question fires for question tools such as ask_question. Set message_end = true to pass message payload text through, truncated by max_message_length; it is off by default to avoid leaking chat content. Leave agent_start = false; it gets noisy.

ignore_nested_pi = true suppresses notifications from a Pi process launched by another Pi agent's bash tool (pi -e, pi -p, etc.). Pi exposes parent-session environment such as PI_SESSION_ID to bash-tool children, so this extension uses that as the cheap nested-process marker.

For agent-controlled completion notifications, set these values under [events]:

agent_settled = false
notify_user = true

Run /reload after enabling the tool. The extension tells the agent to call notify_user once before its final response, after the complete user task is finished—not for delegated tasks or intermediate results. The notification contains only “Task: Finished”, not chat content. Existing defaults and event switches are unchanged. The tool uses the same configuration overrides and notification filters as other events.

Test inside Pi:

/notify-test