// 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.
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.
Inspect macOS network state. Use when getting current WiFi SSID, signal strength, and channel; listing all network interfaces with IP/MAC addresses; or watching for network connect/disconnect events via Darwin notifications.
| name | osascript-launchd |
| description | 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. |
LaunchAgents (per-user, GUI access) and LaunchDaemons (root, system-wide, survives logout). All scripts are pure Python using stdlib only.
| LaunchAgent | LaunchDaemon | |
|---|---|---|
| Runs as | Logged-in user | root |
| Starts when | User logs in | System boot |
| Lives in | ~/Library/LaunchAgents | /Library/LaunchDaemons |
| GUI access | Yes | No |
| TCC restrictions | Yes | No — full system access |
Use LaunchAgent for automation that needs your session (osascript, screen, Chrome). Use LaunchDaemon for always-on background work that needs root or full disk access.
| Trigger | Key | Use case |
|---|---|---|
| On load/login | RunAtLoad: true | Start immediately |
| Keep alive | KeepAlive: true | Restart on any exit (even kill -9) |
| Interval | StartInterval: N | Every N seconds |
| Calendar | StartCalendarInterval | Cron replacement (catches up after sleep) |
| File change | WatchPaths | Instant trigger on file/dir change (no polling) |
| New files | QueueDirectories | Job queue — fires when files appear |
Generate a LaunchAgent plist from parameters:
uv run scripts/generate-plist.py com.user.myjob "/usr/bin/python3 /path/to/script.py" --interval 60
Write plist to ~/Library/LaunchAgents and load it immediately:
uv run scripts/install-agent.py com.user.myjob "/usr/bin/python3 /path/to/script.py" --interval 60
Load, unload, start, stop, or check status of a LaunchAgent:
uv run scripts/launchctl.py status com.user.myjob
uv run scripts/launchctl.py load com.user.myjob
uv run scripts/launchctl.py stop com.user.myjob
<key>WatchPaths</key>
<array>
<string>/Users/you/Library/Messages/chat.db</string>
</array>
Fires instantly when chat.db changes. No polling. Daemon reads new message, Claude processes, osascript sends reply.