Planting a Future Breaking Change Today: A launchd Timer Job That Deletes Itself When Done

A developer created a self-destructing launchd timer job that automatically updates a Claude configuration file on the Fable 5 end-of-life date (2026-07-07) and then unloads itself. The job uses a date gate, a jq rewrite with backup, and self-unload to ensure it runs exactly once on the target day without manual intervention.

This is a follow-up to my earlier post, " Automating a config migration with a one-shot launchd job https://zenn.dev/bokuwalily/articles/one-shot-launchd-migration ." Some breaking changes come with a known expiration date, and you can prepare for them long before they land. This time the external event was the end-of-life of Fable 5 2026-07-07 , and I'll walk through how I designed a launchd job you set up today, that fires only on the target day, and that removes itself once it's done. The whole thing started with the thought, "manually fixing this on the shutdown day is going to be annoying." But I also didn't want to run a script every morning that needlessly rewrites JSON. What I landed on was a three-part set: a date gate, a jq rewrite with a backup, and self-unload. Right now, ~/.claude/settings.json looks like this: { "model": "claude-fable-5 1m ", ... } The moment I learned Fable 5 would end on 2026-07-07, creating a calendar reminder to manually rewrite this "model" felt too flimsy — I'll forget. On the other hand, making "a daemon that checks the date every time it boots" is overkill. What I wanted was a job I could set once and leave alone, that runs when the day arrives, and then disappears. launchd can fire at a specified time via StartCalendarInterval . But you can't express "just once at 9:00 on 7/7"; you need a combination of recurring and date-fixed slots. Specifying multiple slots and absorbing the redundancy with idempotency is the standard trick on macOS launchd. Here's the full ~/.claude/scripts/model-transition-0707.sh comments omitted . bash /bin/bash set -uo pipefail SETTINGS="$HOME/.claude/settings.json" LOG="$HOME/.claude/logs/model-transition.log" PLIST="$HOME/Library/LaunchAgents/com.shun.model-transition-0707.plist" log { echo " $ date '+%F %T' $ " "$LOG"; } ① 日付ゲート if "$ date +%Y%m%d " -lt 20260707 ; then log "skip: before 2026-07-07"; exit 0 fi ② バックアップ付き jq 書き換え current=$ jq -r '.model // empty' "$SETTINGS" if echo "$current" | grep -qi 'fable'; then cp "$SETTINGS" "$SETTINGS.bak-model-transition" jq '.model = "opus"' "$SETTINGS" "$SETTINGS.tmp" \ && jq . "$SETTINGS.tmp" /dev/null \ && mv "$SETTINGS.tmp" "$SETTINGS" log "switched model: $current - opus" /usr/bin/osascript -e \ 'display notification "Fable 5終了に伴いデフォルトモデルをOpusへ切替えました" with title "Claude model transition"' \ /dev/null 2 &1 || true else log "no-op: model is already '$current'" fi ③ 自己 unload launchctl unload "$PLIST" 2 /dev/null || true log "done job unloaded " Let me explain the three parts in order. if "$ date +%Y%m%d " -lt 20260707 ; then log "skip: before 2026-07-07"; exit 0 fi date +%Y%m%d can be compared as an integer since it's a numeric string. 20260706 < 20260707 → skip. That's all. Why this matters: the plist starts firing the instant you launchctl load it today. Even if the 6:50 AM slot fires on the same day you register it, you need it to be a no-op. Without the date gate, on the very day you plant it you'd hit "trying to rewrite even though the model isn't fable" — a misfire. date +%Y%m%d numeric comparison works as-is in macOS's /bin/bash . -lt is an arithmetic comparison, so when the string lengths are equal, lexicographic order and integer order give the same result. cp "$SETTINGS" "$SETTINGS.bak-model-transition" jq '.model = "opus"' "$SETTINGS" "$SETTINGS.tmp" \ && jq . "$SETTINGS.tmp" /dev/null \ && mv "$SETTINGS.tmp" "$SETTINGS" This splits into three steps. | Step | Purpose | |---|---| cp ... .bak-model-transition | Keep the original before rewriting | jq '.model = "opus"' .tmp | Write out to a temp file | jq . .tmp /dev/null | Verify the generated JSON isn't broken | mv .tmp settings.json | Replace the original only after verification passes | If you write jq ... settings.json settings.json directly, the original file is truncated to empty the moment the shell opens the redirect target. Going through a temp file is the basic pattern for avoiding redirect destruction. It's also important that the && chaining means mv isn't run if verification fails. Using grep -qi 'fable' for a case-insensitive check is so it handles "claude-fable-5 1m " and any future variant spellings. The value actually sitting in settings.json is this: "model": "claude-fable-5 1m " After the rewrite it becomes just "opus" an alias, not a model ID. This follows the "don't hardcode model IDs in scripts" policy from CLAUDE.md . launchctl unload "$PLIST" 2 /dev/null || true log "done job unloaded " launchctl unload <plist detaches that job from the daemon. The plist file itself remains, so you can re-register it with launchctl load if needed. I add 2 /dev/null || true so that if it's already unloaded, it doesn't abort with an error. Combined with the idempotent design described below, this guarantees "safe no matter how many times it's called." Note: launchctl unload detaches the job immediately, even while it's running. That's why I call it at the very end of the script — if you didn't remove it only after finishing the rewrite, you'd cut yourself off mid-process. <key StartCalendarInterval</key <array <dict <key Hour</key <integer 6</integer <key Minute</key <integer 50</integer </dict <dict <key Hour</key <integer 12</integer <key Minute</key <integer 50</integer </dict <dict <key Hour</key <integer 20</integer <key Minute</key <integer 50</integer </dict </array Three slots: 6:50, 12:50, and 20:50. "Why not just once?" Because launchd skips any slot while the Mac is asleep. Even if the morning slot passed while asleep, this lets the noon or evening slot catch it. The firing flow on 7/7 is as follows. 6:50 → 日付ゲート通過 → fable 検出 → opus に書き換え → unload → ジョブ消滅 12:50 → ジョブが存在しないので発火しない（unload済み） 20:50 → 同上 Each slot before 7/6 leaves this in the log: skip: before 2026-07-07 and immediately exit 0 . No rewrite happens at all. Diagrammed, it looks like this. 7/5 7/6 7/7 6:50 skip 6:50 skip 6:50 書換+unload ←ここで終了 12:50 skip 12:50 skip 12:50 消滅 20:50 skip 20:50 skip 20:50 消滅 Thanks to idempotency, "set multiple slots and reject early firing with the date gate" holds together. date +%Y%m%d comparison with string comparison < this becomes lexicographic string order, so I switched to -lt . There's no real harm if the 8-digit zero-padding is consistent, but I use arithmetic comparison to make the intent clear. /tmp/ mv can fail to rename across filesystems. Placing it in the same directory $HOME/.claude/ guarantees the same fs. com.shun.model-transition-0707 , or you get "No such process." StandardErrorPath log inside the script writes to its own log file, but StandardErrorPath is still needed as the output destination for when the script itself dies with a syntax error. "$ date +%Y%m%d " -lt YYYYMMDD skips all early firing from the day you plant it onward. launchctl unload $PLIST For things with a fixed deprecation date, "plant it the day you notice and forget about it" is the best approach. It's more reliable than putting an event on the calendar, and easier to cancel than cron. Next time, I might write about how to read the logs this job leaves behind to confirm the migration succeeded — or, if it failed, the recovery procedure from the backup. Written by Lily — I ship iOS apps and automate my content stack with Claude Code. Follow along: Portfolio https://bokuwalily.com · X https://x.com/bokuwalily · GitHub https://github.com/bokuwalily