*zenn.dev*
In previous articles, I've introduced スキルを自動生成する仕組み and コンテキスト監査. These gain value precisely because they run automatically at fixed times every night. In my environment, I currently have 20 launchd jobs running (skill generation, context auditing, morning brief generation, Vault ingestion, etc.).
However, setting up scheduled execution on macOS has far more pitfalls than I imagined. This article covers 5 traps I actually hit and fixed, with verified workarounds.
I registered it with crontab -e, but it never runs once. This is the first trap. On modern macOS (Sequoia and later), the cron daemon is essentially not running, and jobs are silently skipped. You don't even get an error.
Check if it's alive like this.
log show --predicate 'process == "cron"' --last 7d
If this returns 0 results, cron is not running. Migrate straightforwardly to launchd. A launchd job looks like this plist.
<key>Label</key><string>com.you.skill-harvest</string>
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>/Users/you/.claude/scripts/skill-harvest.sh</string>
</array>
<key>StandardOutPath</key><string>/Users/you/.claude/logs/skill-harvest.log</string>
<key>StandardErrorPath</key><string>/Users/you/.claude/logs/skill-harvest.log</string>
Loading and immediate execution work like this.
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.you.skill-harvest.plist
launchctl kickstart gui/$(id -u)/com.you.skill-harvest # 強制実行で動作確認
Key Points
launchctl list / launchctl load are legacy APIs. Modern ones are launchctl print / bootstrap / kickstart. Mixing old and new causes confusion.
Trying to write "every 5 minutes" in cron style gets you stuck. StartCalendarInterval specifies specific times, not periodic syntax like */5.
- Periodic execution → StartInterval (in seconds; 5 minutes = 300)
- Multiple specific times like "N minutes past each hour" → array of StartCalendarInterval entries
Also, these subtle but effective traps:
- Label must be in com.you.name format. Labels without dots are rejected from loading.
- ProgramArguments must be an array (a single string is rejected).
- If you don't explicitly specify StandardOutPath / StandardErrorPath as absolute paths, output disappears into /dev/null.
This is where I got stuck the hardest. Claude Code hooks (PostToolUse, etc.) fail every time with /bin/sh: node: command not found. Yet node works fine in the terminal.
Root cause: Child processes spawned by apps launched from the GUI run /bin/sh -c without reading the login shell profile (.zshrc), having only the minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin). Node in nvm or Homebrew is invisible. launchd jobs fail for the same reason.
The fix is to add env.PATH at the top level of ~/.claude/settings.json and have child processes inherit it.
"env": {
"PATH": "/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/you/.local/bin"
}
The key point is to always include /opt/homebrew/bin. If you hardcode only nvm's version-specific path (.../node/v24.x/bin), it becomes stale the moment you update Node to a major version and you get "not found" again. Including /opt/homebrew/bin/node as a fallback keeps it from breaking.
Reproduction and verification work like this.
# 旧最小PATHで再現（not found が出る）
env -i HOME="$HOME" /bin/sh -c 'PATH="/usr/bin:/bin"; node --version'
# 新PATHで解決（バージョンが出る）
env -i HOME="$HOME" /bin/sh -c 'PATH="/opt/homebrew/bin:/usr/bin:/bin"; node --version'
I wrap scripts with timeout 60 some-command, but get timeout: command not found. macOS doesn't come standard with GNU coreutils' timeout. Many articles and rules are written assuming timeout, so copy-pasting fails silently.
brew install coreutils # gtimeout が入る
Making your script handle both improves portability.
TIMEOUT_CMD="timeout 60"
command -v gtimeout >/dev/null && TIMEOUT_CMD="gtimeout 60"
$TIMEOUT_CMD some-command
Incidentally, bash version issues are the same root cause. macOS's standard bash is 3.2, lacking 5.x features like $EPOCHREALTIME (microsecond-precision timestamps). For measurement scripts, set the shebang to #!/opt/homebrew/bin/bash to explicitly use version 5.
The last one is the most insidious. A certain job with KeepAlive crashed in an infinite loop, repeating approximately 15,000 launches over 6 days. No process ever started, no logs remained. Running launchctl print gui/$(id -u)/<label> showed last exit code = 78: EX_CONFIG, with runs incrementing every few seconds.
78 is not an app exit but a code synthesized by launchd meaning "failed to initialize the service" = failure at the spawn stage. The fact that logs never grew (mtime frozen) confirms this. If manually running the script starts normally, the program itself is healthy and only dies under launchd.
Diffing healthy jobs and plists against the broken one revealed 3 effective causes.
- Log path is in a TCC-protected area (~/Documents, ~/Desktop, etc.) → Change to ~/.claude/logs/ or ~/Library/Logs/ (most likely culprit)
- shebang #!/usr/bin/env bash resolves to an unsigned Homebrew bash in the plist's PATH → Make ProgramArguments explicitly "/bin/bash", "[script.sh"] to specify an Apple-signed interpreter
- WorkingDirectory unspecified → launchd's default cwd is /. If an app writes data via relative paths, it writes to unintended locations (like /tmp which disappears on reboot), losing data
The repair procedure order matters.
# 1. ループを止める
launchctl bootout gui/$(id -u)/<label>
# 2. ポートを掴んだ孤児プロセスを「所有者を確認してから」kill
lsof -nP -iTCP:<port> -sTCP:LISTEN
# 3. plistを直して再投入
launchctl bootstrap gui/$(id -u) <plist>
# 4. 検証
launchctl print gui/$(id -u)/<label> | grep -E 'state =|runs =|last exit'
⚠️ Warning
KeepAlive=true does not fix spawn failures. Without ThrottleInterval (around 30 seconds), the infinite loop at few-second intervals causes runs to accumulate to tens of thousands.
One more landmine. When investigating plists, getting the arguments to plutil -extract ... -o <file> wrong overwrites and corrupts the original plist (I actually had one job's plist become a 76-byte JSON fragment). Always pipe plutil investigation to -o - (stdout) or a separate file.
Automation isn't "done once you set it up"—it's only complete when you include health checks. Getting in the habit of regularly checking launchctl print to see if log mtimes are advancing as expected helps you catch jobs dying silently early.
Over these 3 articles, skills have grown, context has lightened, and automation runs 24/7. Next, I plan to write about the mechanism to summarize all this into a morning brief.
Lily (@bokuwalily) ― Independent developer. Building automation infrastructure with Claude Code while mass-producing iOS apps and web services
◼︎ Apps I've made are summarized at **ポートフォリオ**📱
◼︎ New releases and development behind-the-scenes on X **@bokuwalily**🐦
◼︎ OSS: **github.com/bokuwalily**🐙
Your ❤️ and shares are my motivation!
