Chapter 3: Theory - Understanding macOS Automation

Before we build, let's understand the components that make this work.

The Three Pillars of macOS Automation

1. LaunchAgents (The Orchestrator)

LaunchAgents are macOS services that run in the background and respond to triggers:

• Time-based triggers (run every hour, daily at 6pm, etc.)
• Event-based triggers (system wake, user login, file changes)
• On-demand triggers (socket activation, IPC)

Key characteristics:

• Runs as your user (not root)
• Survives system restarts
• Auto-restarts on failure (configurable)
• Integrates with system logging

2. pmset (The Wake Scheduler)

pmset is macOS's power management tool. The schedule command lets you:

• Wake system from sleep at specific times
• Power on system when off
• Schedule sleep/shutdown/restart

Important limitations:

• Requires sudo privileges
• System must be plugged into power (for reliability)
• Scheduled wakes persist across reboots
• Can have multiple concurrent schedules

3. caffeinate (The Keep-Awake Tool)

caffeinate prevents your Mac from sleeping:

• Holds system awake for specified duration
• Prevents display sleep (optional)
• Prevents disk sleep (optional)
• Can be tied to a running process

Use cases:

• Keep system awake during long-running tasks
• Prevent sleep between sequential automation steps
• Ensure network tasks complete

The Automation Pattern

Here's how these three components work together:

1. pmset schedules wake → System wakes at 6pm
2. LaunchAgent detects wake → Triggers handler script
3. Handler runs caffeinate → Keeps system awake 30 min
4. Handler schedules next wake → pmset wake at 7pm
5. System can sleep → After caffeinate ends
6. Cycle repeats → 7pm wake triggers step 2 again

Real-World Applications

I use this pattern for:

• Nightly data backups - Wake at 2am, backup to cloud, sleep
• Research automation - Wake, scrape data sources, process, sleep
• Content generation - Wake, generate blog posts with AI, publish
• System maintenance - Wake, run updates, cleanup, sleep

The pattern is universal. Once you understand it, you can automate anything that requires scheduled execution.