szoloth/launchd-helper

launchd Helper

Proactive assistant for macOS launchd agents and background automation. Applies learned patterns to prevent common pitfalls.

When This Activates

• Creating or editing .plist files in ~/Library/LaunchAgents/
• Discussing launchd configuration or background jobs
• Debugging agent issues (zombies, permission errors, startup failures)
• Setting up scheduled automation with launchctl

Learned Patterns (Auto-Applied)

1. Always Include TimeoutSeconds

Problem: Without a timeout, hung processes accumulate as zombies.

Rule: Every plist should have TimeoutSeconds set (typically 300-600 for most jobs).

<key>TimeoutSeconds</key>
<integer>300</integer>

Check: If missing, warn and suggest adding it.

2. Use User-Installed Python Path

Problem: /usr/bin/python3 is restricted by macOS security. Scripts fail silently or with permission errors.

Rule: Use the user-installed Python path (typically from Homebrew or pyenv).

<!-- Wrong -->
<string>/usr/bin/python3</string>

<!-- Correct -->
<string>/opt/homebrew/bin/python3</string>
<!-- or -->
<string>~/.pyenv/shims/python3</string>

Check: If /usr/bin/python appears in ProgramArguments, flag it.

3. Use osascript Wrapper for Permission-Sensitive Operations

Problem: launchd agents run in a restricted context. Operations that need user context (GUI access, certain file operations) fail.

Rule: Wrap permission-sensitive scripts in osascript to bypass sandboxing.

<key>ProgramArguments</key>
<array>
    <string>/usr/bin/osascript</string>
    <string>-e</string>
    <string>do shell script "/path/to/your/script.sh"</string>
</array>

Check: If the script interacts with GUI apps, Finder, or user directories, suggest the osascript wrapper.

4. Node.js Process Tree Cleanup

Problem: Node.js child processes (spawn, exec) don't die when the parent is killed. Zombies accumulate.

Rule: Use spawn({detached: true}) and process.kill(-pid) to kill the entire process group.

const child = spawn('command', args, { detached: true });

// Later, to kill the entire tree:
process.kill(-child.pid);

Check: If the launchd agent runs Node.js scripts that spawn children, verify cleanup pattern is used.

Proactive Checks

When I see a plist being created or edited, I will:

1. Scan for TimeoutSeconds - warn if missing
2. Check Python paths - flag /usr/bin/python
3. Identify permission-sensitive operations - suggest osascript wrapper
4. Check for Node.js child processes - verify cleanup pattern
5. Verify Label matches filename - standard best practice
6. Check StandardOutPath/StandardErrorPath - suggest adding for debugging

Example Interaction

User: Create a launchd agent that runs my backup script every hour

Claude: I'll create that agent. Before I do, let me apply the launchd patterns:

✓ Adding TimeoutSeconds (300s) to prevent zombie accumulation
✓ Your script uses Python - using /opt/homebrew/bin/python3 (not /usr/bin)
⚠ Your backup script accesses ~/Documents - wrapping in osascript for permissions
✓ Adding StandardErrorPath for debugging

Here's the plist:
[generates plist with all patterns applied]

Debugging Checklist

When an agent isn't working:

1. Check logs: log show --predicate 'subsystem == "com.apple.launchd"' --last 5m
2. Verify loaded: launchctl list | grep [label]
3. Check exit code: Look in StandardErrorPath log
4. Permission issues?: Try osascript wrapper
5. Python issues?: Verify path with which python3
6. Zombies?: Check TimeoutSeconds, verify process cleanup