| name | osascript-notify |
| description | macOS notifications and system event watching. Use when sending notifications, creating actionable notifications with buttons, watching for screen lock/unlock, detecting network changes, or listening to Darwin/NSDistributedNotification system events. |
osascript-notify
Two notification systems + system event watching. All scripts are Python with JXA embedded.
Two Notification APIs
| displayNotification (simple) | AppleScript dialog (actionable) |
|---|
| Buttons | No | Yes — custom labels |
| User response | No | Yes — returns choice |
| Persistent | No | Yes — blocks until dismissed |
| Setup | Zero | Zero |
Use scripts/notify.py for simple fire-and-forget alerts.
Use scripts/notify-actionable.py for "Proceed? Yes/No" style interactions.
Scripts
Send a simple macOS notification — title, subtitle, body:
uv run scripts/notify.py "Title" "Body text"
uv run scripts/notify.py "Build done" "Tests passed" --subtitle "CI"
Show an actionable dialog with custom buttons — blocks until user responds:
uv run scripts/notify-actionable.py "Deploy to production?"
uv run scripts/notify-actionable.py "Continue?" --buttons "Yes,No,Cancel"
Returns {"choice": "Yes", "cancelled": false} or {"choice": null, "cancelled": true} on Escape.
Watch for screen lock and unlock events (blocking — prints JSON on each state change):
uv run scripts/watch-screen-lock.py
uv run scripts/watch-screen-lock.py --count 3
Reference
Key Darwin Notification Names
| Event | Notification name |
|---|
| Screen locked | com.apple.screenIsLocked |
| Screen unlocked | com.apple.screenIsUnlocked |
| Network change | com.apple.system.config.network_change |
Critical: Never pass null as notification name to NSDistributedNotificationCenter — causes NSNull length crash. Always pass a real string.
