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

This is a follow-up to my earlier post, "Automating a config migration with a one-shot launchd job." 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.

The problem: on the day I learn about a deprecation, I want to plant a job that "only runs on the target day"

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.

The implementation: the three-part set

Here's the full ~/.claude/scripts/model-transition-0707.sh (comments omitted).

#!/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.

① The date gate rejects early firing

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.

② The jq rewrite with a backup

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.

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).

③ Delete yourself after success

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.

The plist: why three slots a day is fine

<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.

Pitfalls I hit

• I had written the date +%Y%m%d comparison with string comparison < → inside bash's [[ ]] 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.
• I had placed the temp file in /tmp/ → mv can fail to rename across filesystems. Placing it in the same directory ($HOME/.claude/) guarantees the same fs.
• I had passed the label as the argument to launchctl unload → you have to pass the full plist path, not the label (com.shun.model-transition-0707), or you get "No such process."
• I had only set StandardErrorPath → the 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.

Summary

• The date gate [ "$(date +%Y%m%d)" -lt YYYYMMDD ] skips all early firing from the day you plant it onward.
• The jq rewrite with a backup is minimally safe as four steps: "cp → jq > tmp → jq verify → mv."
• After success, launchctl unload $PLIST detaches the job. The plist remains, so re-registration is possible.
• The plist's multiple slots are sleep insurance. Because it's idempotent, you can set redundant slots without worry.

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 · X · GitHub*