3 Weeks of Silent Backup Failure: Why launchd Can't Write to ~/Documents on macOS

A developer discovered that their macOS backup job had silently failed for three weeks because launchd couldn't write to ~/Documents due to macOS TCC permissions. The developer solved the issue by moving the backup target to ~/.claude/config-snapshots/ and implementing a two-stage backup system that uses rsync to copy only config files to a separate directory under git, avoiding the noise of the full ~/.claude directory.

Every Sunday at 6:00 AM, my backup job ran, logged no changes , and exited 0. For three weeks straight it never copied a single file. macOS was blocking it, and nothing in the system told me. The first problem you hit when you automate personal development work is "I can't roll back when my config breaks." Once you build out a Claude Code environment, hundreds of lines of configuration accumulate under ~/.claude/ . settings.json tool permissions, model selection, hook paths , CLAUDE.md the full text of global operating rules , the hooks/ directory automated checks like Stop hooks and PreTool hooks , agents/ specialized agent definition files , skills/auto/ skills that get self-generated during real usage , rules/ the ECC rules digest — dozens of places in these change every week. Claude Code updates, hook script improvements, new agent definitions. The more actively you use it, the more the configuration changes like a living thing. The problem is that ~/.claude/ isn't under version control. A Claude Code cache update wipes out a config file, a mistake in a hook script takes down every PreTool hook, a one-line typo in settings.json makes permission prompts explode everywhere — and when that happens, with no diff and no history, you can't even tell when it broke. Reconstructing by feel from "it was working a week ago" is pure lost time. The two approaches most people reach for here are "back it up manually" or "put the whole thing in git." Manual backups get tedious even at weekly cadence. And your environment breaks precisely during the week you skipped. "I was going to get around to it" doesn't help you recover. The whole thing in git doesn't work in practice, because ~/.claude/ mixes in noise like plugin cache, session history, telemetry, and paste-cache, which balloons the repository to several GB. It also can't rule out the risk of secrets ending up in the cache. The solution is a two-stage structure: rsync only the config files to a separate directory, and put only that directory under git. Never touch ~/.claude/ itself, and define the sync targets explicitly with an INCLUDE list. Even when the human forgets, launchd runs every Sunday at 6:00. If there's a diff, commit it in conventional commits format. If there's no diff, write no changes to the log and exit. This works because it takes human willpower out of the loop . Config files are too fine-grained to manage on the strength of "I should really back this up." But losing them costs hours to reconstruct. Automation fills that asymmetry, and launchd sits at the bottom layer of that automation as a highly reliable OS feature. There are side benefits too. Because the diffs stay in git, you can track down "which change last week broke the hook" with git log --oneline . You can discover configuration drift parts that changed unintentionally . You can reproduce the setup immediately when moving to another machine. You can build up improvements while checking "what did I do a week ago" with git diff . The header comment of the actual script ~/.claude/scripts/dotfiles-snapshot.sh reads like this: dotfiles-snapshot.sh — ~/.claude の設定だけを別ディレクトリに同期して git 管理 元の ~/.claude は触らない（plugin cache 等のノイズと混ざらないため） 同期先: ~/.claude/config-snapshots/ （旧 ~/Documents/claude-config-snapshots は launchd 実行時に macOS TCC で "Operation not permitted" になり全コピー失敗していたため 2026-06-01 に移設） 既存 ~/Documents/my-knowledge-base/ の SessionEnd auto-commit と分離管理 The line "never touch the original ~/.claude " expresses the design philosophy. The backup source directory itself isn't under git; only the necessary config files are copied to a separate directory, and only that becomes a repository. The INCLUDE list is the "canonical definition" of what counts as a config file. And the fourth line of that comment — the old ~/Documents/claude-config-snapshots hit macOS TCC "Operation not permitted" when run under launchd and every copy failed, so it was relocated on 2026-06-01 — is the actual subject of this article. Before that relocation on 2026-06-01, the backup ran every Sunday at 6:00 "looking like it worked" while doing nothing at all. Here's the structure of the current system. ┌─────────────────────────────────────────────────────────┐ │ launchd │ │ Label: com.shun.dotfiles-snapshot │ │ 毎週日曜 06:00 │ │ ProcessType: Background / Nice: 10 / LowPriorityIO: true│ └──────────────────────┬──────────────────────────────────┘ │ /bin/zsh -c <script ▼ ┌─────────────────────────────────────────────────────────┐ │ dotfiles-snapshot.sh │ │ │ │ SRC: ~/.claude/ │ │ DST: ~/.claude/config-snapshots/ ← 重要 │ │ │ │ 1. INCLUDE 11項目を rsync -a でコピー │ │ 2. settings.json に APIキー混入チェック │ │ 3. git add -A && git commit 変更ゼロなら skip │ │ 4. HEAD 前進チェック（exit 0 でも HEAD 不動なら exit 3） │ └──────────────────────┬──────────────────────────────────┘ │ ┌────────┴────────┐ ▼ ▼ ┌─────────────────┐ ┌──────────────────────────────────┐ │ git repository │ │ ~/.claude/logs/ │ │ config-snapshots│ │ dotfiles-snapshot.log │ │ conventional │ │ com.shun.dotfiles-snapshot.log │ │ commits │ │ （plist StandardOutPath と共用） │ └─────────────────┘ └──────────────────────────────────┘ Let's look at the core of the plist. <key StartCalendarInterval</key <dict <key Hour</key <integer 6</integer <key Minute</key <integer 0</integer <key Weekday</key <integer 0</integer </dict <key ProcessType</key <string Background</string <key LowPriorityIO</key <true/ <key Nice</key <integer 10</integer Weekday=0 is Sunday. Nice=10 and LowPriorityIO=true are appropriate settings for a 6 AM background job — they avoid competing for IO with the workload spike right after startup. It's weekly rather than daily because config changes are coarser-grained than daily. Claude Code configuration alternates between "weeks I touched a ton" and "weeks I didn't touch at all." Weekly gives sufficient diff resolution. Log output is split across two destinations. <key StandardErrorPath</key <string ~/.claude/logs/com.shun.dotfiles-snapshot.log</string <key StandardOutPath</key <string ~/.claude/logs/com.shun.dotfiles-snapshot.log</string The plist-level stdout/stderr are written by launchd. Logging inside the script flows to LOGFILE="$HOME/.claude/logs/dotfiles-snapshot.log" . Since the script does echo " $ ts ..." "$LOGFILE" , launchd's startup log and the script's progress log get recorded in two separate files. Next, the INCLUDE list. The script's backup targets are these 11 items: INCLUDE= "settings.json" "settings.local.json" "CLAUDE.md" "hooks/" "commands/" "agents/" "skills/auto/" "skills/ecc/" "scripts/" "rules/" "improvements/" Cache, session, telemetry, paste-cache, and file-history are nowhere in there. Conversely, look at the EXCLUDES list: EXCLUDES= "--exclude= .log" "--exclude=.cache/" "--exclude=node modules/" "--exclude= .tsbuildinfo" "--exclude=.harvest-watermark" "--exclude=tmp/" --exclude=.harvest-watermark stands out. That's a watermark file generated by Claude Code's automatic skill-harvesting feature, and it becomes diff noise if it makes it into commits. By explicitly excluding environment-specific junk, git log records only meaningful configuration changes. The rsync loop is simple. for item in "${INCLUDE @ }"; do if -e "$SRC/$item" ; then rsync -a "${EXCLUDES @ }" "$SRC/$item" "$DST/$item" 2 "$LOGFILE" fi done Because it checks existence with -e "$SRC/$item" before rsyncing, an item that's listed in INCLUDE but hasn't been created yet is harmlessly skipped. Errors flow to the log via 2 "$LOGFILE" , so you can check afterward what happened during the run. Before committing, an API key detection check runs. if grep -qE 'sk- A-Za-z0-9 - {30,}|ghp A-Za-z0-9 {30,}|AKIA 0-9A-Z {16}' \ "$DST/settings.json" 2 /dev/null; then echo " $ ts ABORT: secret detected in settings.json copy" "$LOGFILE" rm -f "$DST/settings.json" exit 1 fi It greps for three patterns: sk- Anthropic API key , ghp GitHub Personal Access Token , and AKIA AWS Access Key . If you accidentally wrote an API key into settings.json, it deletes the copied file and terminates immediately with exit 1. The three steps — detect secret, delete the copy, abort — are consolidated in one place, so it stays safe even combined with pushing to a public repository. The commit logic has one more defense. PREV HEAD=$ git rev-parse --verify --quiet HEAD || echo "" if git commit -m "chore snapshot : claude-config $ date '+%Y-%m-%d %H:%M' " \ "$LOGFILE" 2 &1; then NEW HEAD=$ git rev-parse --verify --quiet HEAD || echo "" if -z "$NEW HEAD" || "$NEW HEAD" = "$PREV HEAD" ; then echo " $ ts commit reported success but HEAD did not advance \ prev=$PREV HEAD new=$NEW HEAD — ABORT" "$LOGFILE" exit 3 fi COMMIT=$ git rev-parse --short HEAD echo " $ ts snapshot done: ${CHANGED} files changed, commit=${COMMIT}" "$LOGFILE" Even if git commit returns exit 0, if HEAD hasn't moved it terminates abnormally with exit 3. A comment in the script says 前は -q で潰していて exit code も拾えていなかった "previously -q suppressed it and the exit code wasn't captured either" , and this was implemented as a countermeasure for a past bug where the commit hook commit-msg validator rejected the commit but the exit code appeared to be 0 . The line commit reported success but HEAD did not advance in the log lets you trace the cause quickly. A normal run's log looks like this: 2026-06-08 06:00:12 snapshot start 2026-06-08 06:00:13 snapshot done: 3 files changed, commit=a1b2c3d And with no diff: 2026-06-08 06:00:12 snapshot start 2026-06-08 06:00:12 no changes Just those two lines tell you whether the backup ran and whether anything changed. No dashboard, no notifications needed. You only open the log when something goes wrong. That's the full picture of the current correctly working system. So what was happening before 2026-06-01, when the backup destination was ~/Documents/claude-config-snapshots/ ? Where did the "Operation not permitted" from that header comment come from, and why did everything fail silently? The next section breaks down the evidence. -e isn't added to set -uo pipefail The script starts with set -uo pipefail . Undefined variable references -u and mid-pipeline errors -o pipefail kill the script immediately, while -e exit immediately on any non-zero command is deliberately left out. There are two reasons. The first is the secret check. if grep -qE 'sk- A-Za-z0-9 - {30,}|ghp A-Za-z0-9 {30,}|AKIA 0-9A-Z {16}' \ "$DST/settings.json" 2 /dev/null; then echo " $ ts ABORT: secret detected in settings.json copy" "$LOGFILE" rm -f "$DST/settings.json" exit 1 fi grep -q returns exit code 1 when the pattern is not found i.e., no API key present, the normal state . Enabling -e would produce the backwards behavior of "no secret present = normal = exit 1 = script aborts." Since if grep ... makes the control flow explicit, -e isn't just unnecessary — it's harmful. The second is HEAD retrieval. PREV HEAD=$ git rev-parse --verify --quiet HEAD || echo "" git rev-parse HEAD returns exit 1 right after git init when no commit exists yet . || echo "" falls back to an empty string so the first run works safely too, but with -e the script would die before the || is evaluated. In a design that controls failures with explicit exit 1 / exit 2 / exit 3 , -e is noise. set -uo pipefail expresses a deliberate policy: "kill on undefined variables and mid-pipeline errors; handle command non-zero returns myself." The plist's EnvironmentVariables block enumerates a complete PATH including nvm-managed Node.js, Homebrew, and ~/.local/bin . Background processes launched by launchd read neither ~/.zshrc nor ~/.zprofile . The default PATH is barely more than /usr/bin:/bin:/usr/sbin:/sbin and doesn't even include /opt/homebrew/bin . git and rsync live in the system's /usr/bin , but git hooks that need Node.js will absolutely jam. This script itself is written with only bash, rsync, and git, and doesn't call node.js directly. So why is the Node.js path needed? Because the global git hook ~/.git-hooks/commit-msg calls a Node-based validator in some environments when verifying conventional commits format. With an incomplete PATH, you end up in a situation where git commit runs but the hook silently fails every time.Writing the full PATH into the launchd process is a one-time cost. Far cheaper than getting stuck later on "for some reason only git commit fails." The plist says this: <key StandardErrorPath</key <string ~/.claude/logs/com.shun.dotfiles-snapshot.log</string <key StandardOutPath</key <string ~/.claude/logs/com.shun.dotfiles-snapshot.log</string But the execution string in ProgramArguments contains a shell-level redirect. <string /bin/zsh</string <string -c</string <string /path/to/dotfiles-snapshot.sh /dev/null 2 &1</string With /dev/null 2 &1 , the script's own stdout/stderr are thrown into /dev/null at shell evaluation time. The fd that launchd set up via StandardOutPath gets overwritten. So what is StandardOutPath actually capturing? The answer is "zsh's own startup errors." If zsh fails before evaluating the -c string — a broken script path, zsh not found, and so on — that error flows to the fd launchd set up, ahead of the shell-level redirect. com.shun.dotfiles-snapshot.log functions not as the script's progress log but as a fallback that catches launchd-layer startup failures . The script's progress is recorded via explicit writes to LOGFILE="$HOME/.claude/logs/dotfiles-snapshot.log" . ts { date '+%Y-%m-%d %H:%M:%S'; } echo " $ ts snapshot start" "$LOGFILE" This two-path separation lets you track "did the script start launchd log " and "what happened inside the script dotfiles-snapshot.log " in separate files. The starting point for troubleshooting is the latter. The rsync loop sends errors to the log but doesn't stop the loop. for item in "${INCLUDE @ }"; do if -e "$SRC/$item" ; then rsync -a "${EXCLUDES @ }" "$SRC/$item" "$DST/$item" 2 "$LOGFILE" fi done It doesn't check rsync's exit code. This is an intentional design. If the agents/ copy fails on a permission error, I don't want that to stop the CLAUDE.md or hooks/ copies too. The idea is: tolerate partial failure, copy as many files as possible, and leave errors in the log. But this design also means "the script exits normally even if every item errors." If nothing gets copied to DST, no diff appears in git, and it records no changes and finishes. The TCC bug described later is exactly this case. grep -qE 'sk- A-Za-z0-9 - {30,}|ghp A-Za-z0-9 {30,}|AKIA 0-9A-Z {16}' sk- is an Anthropic API key, ghp a GitHub Personal Access Token, and AKIA an AWS Access Key ID. settings.json is where you write Claude Code tool permissions and model settings, so these three families are chosen because they're the ones you might accidentally hardcode. A generic "long alphanumeric string" pattern produces too many false positives, so the policy is to narrow by prefix. When something is detected, it deletes the copied file and then exits 1 . If you exit 1 with the copied file still there, the next run records the "deleted state" as a diff and leaves contamination in the git log. The order — delete, then exit 1 — matters. Symptom : launchd starts every Sunday at 6:00. The log shows 2026-05-xx 06:00:12 snapshot start and 2026-05-xx 06:00:12 no changes lined up weekly. At a glance, it looks like it's working fine. But when I checked ~/.claude/config-snapshots/.git/ , git log had stopped at a commit from a month earlier. ~/.claude/CLAUDE.md had 50 lines added last week, but the snapshot repository's copy was still the old one. Cause : The reason for no changes wasn't "no changes in the config files" but "rsync couldn't copy anything, so no diff appears in DST." The backup destination at the time was ~/Documents/claude-config-snapshots/ . Picking up rsync's error log, the same line was repeated for all 11 items. rsync: sender send files failed to open ".../Documents/claude-config-snapshots/..." : Operation not permitted 1 macOS TCC Transparency, Consent, and Control was blocking writes to ~/Documents/ . TCC is macOS's mechanism for protecting user data. Access to ~/Desktop/ , ~/Documents/ , ~/Downloads/ , and external storage prompts for permission via a system dialog on an app's first access. But background processes launched by launchd get no dialog . Without permission, it quietly returns Operation not permitted with no user notification and no warning log. rsync's errors were being written to the log file via 2 "$LOGFILE" , but the script body proceeds to the next item without checking that exit code. Even if all 11 items fail, if DST is unchanged then CHANGED=0 and it records no changes and exits normally. Fix : I relocated the backup destination to ~/.claude/config-snapshots/ 2026-06-01 . ~/.claude/ is a dot folder directly under the home directory and isn't among TCC's protected targets Desktop/Documents/Downloads . Even a launchd background process can read and write it without access restrictions. After the relocation, rsync copied all items correctly, and the first commit recorded hundreds of lines of diff at once. That was the moment "three weeks of configuration changes had been treated as if they never happened" first became visible. The single line in the script's header comment the old ~/Documents/claude-config-snapshots hit macOS TCC "Operation not permitted" when run under launchd and every copy failed, so it was relocated on 2026-06-01 is there to pass this lesson on to future me. The asymmetry between TCC and launchd : When a GUI app accesses ~/Documents/ for the first time, the system shows a permission dialog. The user gets to notice "ah, this app is trying to write there." A launchd background daemon has no such feedback. The gap between "looks successful" and "actually failed" goes unclosed for weeks because no notification mechanism exists. When writing automation on macOS, the places you can safely write to from launchd are ~/. -style dot folders, /tmp/ , and app containers. You have to accept ~/Documents/ as protected territory for GUI apps. git commit emitted a "success log" while HEAD didn't move Symptom : The log says 2026-xx-xx 06:00:13 snapshot done: 5 files changed, commit=a1b2c3d . It even records the commit hash. But running cd ~/.claude/config-snapshots && git log --oneline , that hash doesn't exist. It hasn't moved from a commit a week earlier. Cause : The global commit-msg hook was rejecting the commit, but that wasn't being communicated to the script. The commit execution code at the time had the -q quiet flag. 旧コード（問題版） if git commit -q -m "chore snapshot : claude-config $ date '+%Y-%m-%d %H:%M' "; then echo " $ ts snapshot done: ..." "$LOGFILE" fi -q suppresses git's stdout output. The problem is recorded in a comment. stdout/stderr を両方 LOG に流す（前は -q で潰していて exit code も拾えていなかった） With stdout suppressed by -q , there were cases where the exit code the script received appeared to be 0 even when the ~/.git-hooks/commit-msg validator returned non-zero and aborted the commit. The if git commit -q ... condition evaluated true, and the log recorded it as "succeeded." Before the HEAD-advancement check was added, "a hash appears in the commit log" was the only means of confirming normal operation, so looking at the log told you nothing about the cause. Fix : I made two changes at once. First, drop -q and send both stdout and stderr to $LOGFILE . if git commit -m "chore snapshot : claude-config $ date '+%Y-%m-%d %H:%M' " \ "$LOGFILE" 2 &1; then Next, explicitly confirm HEAD advanced. PREV HEAD=$ git rev-parse --verify --quiet HEAD || echo "" ... commit実行後 ... NEW HEAD=$ git rev-parse --verify --quiet HEAD || echo "" if -z "$NEW HEAD" || "$NEW HEAD" = "$PREV HEAD" ; then echo " $ ts commit reported success but HEAD did not advance \ prev=$PREV HEAD new=$NEW HEAD — ABORT" "$LOGFILE" exit 3 fi The reason for the custom exit 3 code is the LastExitStatus value you can check with launchctl list com.shun.dotfiles-snapshot . launchd stores the script's exit code as code × 256 . If LastExitStatus is 768 , that's 3 × 256 , so you know it terminated with exit 3 . By distinguishing exit 2 commit failure , exit 3 HEAD didn't move , and exit 1 secret detected , you can identify the failure type from the exit code without looking at a dashboard. Never trust the commit exit code : You must not judge git commit 's success by exit code alone. commit-msg hooks, pre-commit hooks, and post-commit hooks run inside git's process, and exit code propagation varies with the git version and the hook implementation. Directly checking "did HEAD advance" with git rev-parse is the only reliable verification method. git init always ended in exit 3 Symptom : When I deleted the backup destination directory manually and retested, the first run always terminated with exit 3 . The log said commit reported success but HEAD did not advance prev= new= — ABORT . This surfaced right after adding the HEAD-advancement check. Cause : A freshly git init ed repository has no HEAD no commits at all . So PREV HEAD="" . If the commit succeeds, NEW HEAD gets the new hash and -z "$NEW HEAD" should be false. But the comment records: 過去バグ: 初回 init 時 validator が弾いたのに success ログ "past bug: on first init the validator rejected it but a success log was written" . When the commit-msg hook rejects, NEW HEAD stays "" . The check condition is -z "$NEW HEAD" || "$NEW HEAD" = "$PREV HEAD" , so: PREV HEAD="" and NEW HEAD="abc1234" → left side false, right side false → check passes PREV HEAD="" and NEW HEAD="" → left side true → exit 3These two patterns are handled by one line with || . The exit 3 during testing was the "first run plus hook error" combination. The commit-msg hook was rejecting the state where git config's user.name and user.email were unset. The script does have a line that writes repo-local settings at git init time inside the first-init block , but in my test I had manually deleted only .git/ , so the user settings didn't remain and the hook refused. if -d "$DST/.git" ; then cd "$DST" && git init -q && git config user.name "..." && git config user.email "..." echo " $ ts git init at $DST" "$LOGFILE" fi If you delete all of DST and rerun, the order mkdir -p "$DST" → git init → user settings → commit success is guaranteed. Deleting only .git/ produces "partial initialization" and breaks that ordering. My test procedure was wrong. The correct reproduction test procedure : Delete everything with rm -rf "$DST" , then start manually with launchctl start com.shun.dotfiles-snapshot . Partial deletion creates a half-baked state and complicates debugging. A flaw in the test procedure was manufacturing a bug that doesn't reproduce in production, since production launchd always starts from mkdir -p "$DST" . In the section above I dug into three cases: "the TCC bug where no backups were taken for three weeks," "the bug where git commit returned exit 0 while HEAD didn't move," and "the bug where the first commit right after git init exits 3." Here I'll cover the other pitfalls you commonly hit in a launchd × rsync × git setup. You can't use ~ in plist path values write absolute paths launchd interprets the XML values of StandardOutPath and StandardErrorPath literally. ~ is a shell expansion feature, and the plist parser has no such logic. Even if you write ~/.claude/logs/... , launchd goes looking for a path literally named ~/.claude/ , which of course doesn't exist, so the output is lost. The actual plist writes absolute paths like this: <key StandardErrorPath</key <string /Users/home dir/.claude/logs/com.shun.dotfiles-snapshot.log</string <key StandardOutPath</key <string /Users/home dir/.claude/logs/com.shun.dotfiles-snapshot.log</string A plist copied from a template and reused with ~ intact will keep running while producing no logs whatsoever. If you find yourself thinking "it's launching under launchd but I can't capture zsh startup errors," check here first. Shell redirects in ProgramArguments override StandardOutPath <string /bin/zsh</string <string -c</string <string /path/to/dotfiles-snapshot.sh &gt;&gt; /dev/null 2&gt;&amp;1</string When you write /dev/null 2 &1 , the write destination that launchd set via StandardOutPath gets replaced with /dev/null at the zsh level. As explained above, this design is an intentional separation: "capture only zsh errors before the script starts via StandardOutPath ." But if you do it unintentionally, you end up with "nothing shows up in the launchd log." While debugging, the safe procedure is to temporarily remove /dev/null so output flows to StandardOutPath, then restore it once you've confirmed behavior. Omitting EnvironmentVariables means neither Homebrew nor nvm is visible launchd background processes read neither .zshrc nor .zprofile . The default PATH is effectively /usr/bin:/bin:/usr/sbin:/sbin . git and rsync happen to be in the system's /usr/bin so they work, but Homebrew's git a newer version and nvm-managed Node.js are invisible. The problem becomes visible in the case where the global git hook is Node-based . This script itself doesn't call Node.js directly. But if a conventional commits validator like ~/.git-hooks/commit-msg is written in Node, Node.js becomes indirectly required. The actual plist writes the full PATH like this: <key PATH</key <string /Users/home dir/.nvm/versions/node/v24.13.0/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/home dir/.local/bin</string You need to update this path every time the nvm version changes. Rewrite it based on the version you check with nvm current . StartCalendarInterval skips scheduled runs during sleep One of the big differences between cron and launchd is how missed fires are handled. If the Mac was asleep at 6 AM Sunday, the StartCalendarInterval launch is silently skipped. There's no catch-up behavior after wake. It won't run until the next Sunday at 6 AM. In an environment where you frequently shut down or sleep a laptop, a weekly schedule risks leaving holes. There are two countermeasures: switch to fixed-interval execution with StartInterval e.g., 86400 seconds = daily , or add RunAtLoad: true so it also runs at load time. Running daily greatly reduces the probability of a gap longer than a week. Confusing launchctl load with launchctl start launchctl load ~/Library/LaunchAgents/com.shun.dotfiles-snapshot.plist only registers the schedule. It doesn't run immediately. Doing load while debugging and then agonizing for 10 minutes over "why isn't it running" is an extremely common way to get stuck. Immediate execution is launchctl start com.shun.dotfiles-snapshot . The test cycle is as follows. plistを更新した場合 launchctl unload ~/Library/LaunchAgents/com.shun.dotfiles-snapshot.plist launchctl load ~/Library/LaunchAgents/com.shun.dotfiles-snapshot.plist launchctl start com.shun.dotfiles-snapshot 実行後に確認 launchctl list com.shun.dotfiles-snapshot → "LastExitStatus" = 0 なら正常 How to read LastExitStatus what does 768 mean? When launchctl list com.shun.dotfiles-snapshot outputs "LastExitStatus" = 768 , that's 768 ÷ 256 = 3 , meaning it terminated with exit 3 . launchd stores the script's exit code as exit code × 256 . This script assigns the following meanings to its exit codes: 0 — normal termination changes committed successfully, or no changes 1 — secret detected in settings.json; copy deleted and aborted 2 — git commit failed with a non-zero exit 3 — git commit exited 0 but git rev-parse HEAD shows HEAD didn't advanceChecking LastExitStatus with launchctl list before opening the log is the fastest first move when something breaks. You have to maintain the INCLUDE list yourself Even if you create a new directory in ~/.claude/ , it won't be backed up unless you add it to the script's INCLUDE list. INCLUDE= "settings.json" "settings.local.json" "CLAUDE.md" "hooks/" "commands/" "agents/" "skills/auto/" "skills/ecc/" "scripts/" "rules/" "improvements/" In my environment, I ran a memory/ directory files written by agentmemory for a month before noticing "that's not in INCLUDE." The commit the week I added it was the first time that month's worth of changes made it into a snapshot. Get in the habit of reconciling ls ~/.claude/ against this list monthly. The script rewrites .gitignore every run The script overwrites .gitignore from a heredoc on every run. cat "$DST/.gitignore" << 'GITIGNORE' Auto-generated by dotfiles-snapshot.sh .log .DS Store tmp/ ... GITIGNORE Anything you append to .gitignore by hand disappears on the next run. If you want to add exclusion patterns, edit the heredoc in the script body. The Auto-generated comment signals that intent. 2 "$LOGFILE" alone won't make you notice rsync errors rsync sends errors to the log inside the loop, but proceeds to the next item without checking the exit code. for item in "${INCLUDE @ }"; do if -e "$SRC/$item" ; then rsync -a "${EXCLUDES @ }" "$SRC/$item" "$DST/$item" 2 "$LOGFILE" fi done Even if all 11 items fail, it's CHANGED=0 → no changes → normal exit. If you get the nagging feeling that " no changes has continued for weeks even though I'm sure I changed the config," check the log with this command: grep "Operation not permitted\|rsync error" ~/.claude/logs/dotfiles-snapshot.log | tail -20 If anything shows up, that leads you to the cause. TCC protected targets aren't just ~/Documents/ The TCC problem detailed above isn't limited to ~/Documents/ . The directories where a launchd background process gets silently blocked are: ~/Desktop/ ~/Documents/ ~/Downloads/ ~/Movies/ , ~/Music/ , ~/Pictures/ ~/Library/Mobile Documents/ Conversely, the directories launchd can write to without permission are: ~/ ~/.claude/ , ~/.config/ , ~/.local/ , etc. ~/Library/Application Support/ , ~/Library/Logs/ , ~/Library/Caches/ /tmp/ , /var/folders/ temporary files Before designing an automation script, confirm which of these two lists its write destination belongs to. Set git's local user config at the same time as git init The global ~/.gitconfig is normally read even in a launchd environment, but if a commit-msg hook assumes the existence of user.name / user.email , it can be rejected when something like GIT CONFIG NOSYSTEM is set in the launchd environment. That's why this script writes git config user.name "..." and git config user.email "..." locally at the same time as git init — as a failsafe. if -d "$DST/.git" ; then cd "$DST" && git init -q \ && git config user.name "..." \ && git config user.email "..." fi Unless you delete all of DST before retesting, the git init block won't execute. A test that deletes only .git/ creates a "partially initialized" state and induces bugs that don't reproduce in production see Stuck 3 above for details . ~/Documents/ as a backup destination launchd background processes get rejected silently. The first choice for a backup destination is a ~/. -style dot folder. This setup's ~/.claude/config-snapshots/ is the correct example. If you use ~ , that character isn't expanded and doesn't function as a path. StandardOutPath , StandardErrorPath , the script path inside ProgramArguments — write them all in /Users/username/... absolute path form. The default PATH is basically /usr/bin:/bin . Unless you explicitly include /opt/homebrew/bin , the nvm-managed Node.js path, and ~/.local/bin , it's no surprise when a tool your script depends on stops being found. The fastest way to get the PATH is from echo $PATH in the shell you're currently working in. git commit success directly with git rev-parse HEAD Don't trust the exit code. Exit code propagation is unstable depending on commit-msg hooks, pre-commit hooks, and the hook implementation. Comparing PREV HEAD and NEW HEAD to directly confirm "did HEAD advance" is the only reliable means. PREV HEAD=$ git rev-parse --verify --quiet HEAD || echo "" git commit -m "chore snapshot : ..." "$LOGFILE" 2 &1 NEW HEAD=$ git rev-parse --verify --quiet HEAD || echo "" -z "$NEW HEAD" || "$NEW HEAD" = "$PREV HEAD" && exit 3 Assigning exit 1 secret detected , exit 2 commit failure , and exit 3 HEAD didn't move means you can identify the cause type just by dividing launchctl list 's LastExitStatus by 256. If you only use a generic exit 1 , you have to read through logs afterward to trace "what did it fail on." grep -qE 'sk- A-Za-z0-9 - {30,}|ghp A-Za-z0-9 {30,}|AKIA 0-9A-Z {16}' A generic pattern like "30+ alphanumeric characters" also catches Base64-encoded config values. Narrowing by prefix — sk- Anthropic , ghp GitHub PAT , AKIA AWS — covers the substantive risk while keeping false positives near zero. Catch zsh startup errors with StandardOutPath , and send the script's internal progress to a separate file with "$LOGFILE" . This two-path separation lets you track "did the script start" and "what happened inside the script" independently. The first step in troubleshooting is: launchctl list → check LastExitStatus → check dotfiles-snapshot.log . set -uo pipefail and deliberately leave out -e Undefined variables -u and pipeline interruptions -o pipefail should kill the script. But -e doesn't play well with a secret check where grep -q treats "pattern not found exit 1 " as normal, or with first-init handling that has a git rev-parse ... || echo "" fallback. Leaving -e out and explicitly handling non-zero returns with if makes the intent clearer. It's important to keep copying the rest even when 1 of 11 items fails. Proceed to the next item without checking rsync's exit code, and record errors with 2 "$LOGFILE" . But note that in this design, even a total failure of every item ends in no changes . Check the log for Operation not permitted periodically. launchctl start and check LastExitStatus with launchctl list When you change the plist, test immediately with the unload → load → start cycle. If launchctl list com.shun.dotfiles-snapshot 's LastExitStatus isn't 0, trace the cause in this order: divide by 256 to identify the type → check the log. Waiting for the next scheduled run is a waste of time. Nice=10 and LowPriorityIO=true as a set <key LowPriorityIO</key <true/ <key Nice</key <integer 10</integer <key ProcessType</key <string Background</string Nice=10 alone only lowers CPU priority. If you omit LowPriorityIO: true , IO runs at normal priority and competes with other writes on a freshly booted Mac. For background backups, specify all three as a set. ls ~/.claude/ Every time a new directory appears in ~/.claude/ , it needs to be added to the INCLUDE list. Either build the habit of comparing ls ~/.claude/ against the list monthly, or run this command periodically: INCLUDE未収録のディレクトリを抽出する例 comm -23 < ls ~/.claude/ | sort \ < echo -e "CLAUDE.md\nhooks\ncommands\nagents\nskills\nscripts\nrules\nimprovements\nconfig-snapshots\nlogs\nsettings.json\nsettings.local.json" | sort rm -rf "$DST" Retesting after deleting only .git/ creates a "partially initialized" state and produces bugs that don't reproduce in production. Always start tests from a state where all of $DST has been deleted. Since production launchd always starts from mkdir -p "$DST" , this fully reproduces that condition. The core thing I wanted to convey in this article is the structure of the "looks successful but actually failed" trap . macOS TCC shows GUI apps a dialog asking "allow access?" The user learns that the app is trying to write to ~/Documents/ . But a launchd background process has no such feedback. Operation not permitted flows into the log as an rsync error, the script proceeds to the next item, and even with every item failing it records no changes and exits normally. launchd's LastExitStatus is 0. The signal conveyed to the user is zero. git commit 's exit code had the same structure. Even when a hook rejects, it can look like exit 0. Even when the log says commit=a1b2c3d , that hash may not exist in git log . A log record saying "succeeded" does not guarantee that it actually succeeded. The common remedy for both traps is "confirm facts that are verifiable from the outside." Not "did rsync succeed" but "does the file exist at the destination." Not "did the git commit succeed" but "did HEAD advance," confirmed with git rev-parse . "The command returned exit 0" is not the same as "the intended side effect happened." One of the reasons I spent half a year building out my Claude Code autonomous environment was to find and eliminate these "silent failures" one by one. The environment rests less on flashy AI usage than on an accumulation of unglamorous defensive lines. The line left in the script's header comment — the old ~/Documents/claude-config-snapshots hit macOS TCC "Operation not permitted" when run under launchd and every copy failed, so it was relocated on 2026-06-01 — is the lesson learned from three weeks of silent failure. The code is simple. dotfiles-snapshot.sh is 112 lines: rsync over the INCLUDE list, the secrets check, the HEAD-advancement check, and log output. That's it. The complexity came not from the design but from accurately understanding macOS behavior. 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