// 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.
| 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. |
Two notification systems + system event watching. All scripts are Python with JXA embedded.
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.
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
| 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.
Script macOS apps via AppleScript/JXA: Mail, Calendar (EventKit attendees), Notes, Reminders, Finder (disk/file info), and Spotlight/mdfind (full-text and metadata search across the file system).
Control macOS system audio via osascript. Use when getting or setting system volume, toggling mute, listing audio input/output devices, or checking which device is the default output.
Automate Google Chrome with osascript/JXA. Use when listing/focusing/closing/navigating/reloading tabs, muting tabs, managing windows, executing JavaScript, scraping page content, extracting links, filling forms, reading localStorage/cookies/audio state, or reading Chrome history/bookmarks/downloads/extensions/profiles.
Read and write the macOS clipboard with full type support. Use when reading clipboard text, HTML, RTF, images, or file paths (Finder copy); writing rich content; detecting clipboard changes via changeCount; or intercepting content between copy and paste.
Read macOS app SQLite databases directly. Use when reading iMessage chat history, Chrome browsing history, Safari history, or any local app SQLite DB. Always copy the DB before querying — most apps lock the file while running.
Create and manage macOS LaunchAgents and LaunchDaemons. Use when setting up background automation, scheduled tasks, file watchers (WatchPaths), interval polling, or persistent daemons that survive logout or reboot.
