Automated sync of AI tool configs via hybrid watcher + daily PR¶
- Date: 2026-03-09
- Status: Superseded by 0033
- Tags:
workflowtoolingprocess
Context¶
AI tool configurations (Windsurf rules, skills, workflows; Claude Code skills,
hooks, rules) live scattered across ~/.windsurf/ and ~/.claude/ on the
local machine. This repo is intended to be the canonical knowledgebase for
those configs, but keeping it current required manual copy-paste after every
change — a step that was consistently skipped in practice.
The result: the repo drifted from reality, losing the value of having a version history. Any attempt to reconstruct what changed required comparing files by hand.
Several constraints shaped the solution:
- Changes to tool configs happen frequently and unpredictably (a Windsurf rule edit, a skill tweak mid-session)
- Committing on every single file save would create a noisy, low-signal history
- A daily batch is too coarse — a day's work could span many meaningful, distinct changes to different tool configs
- The laptop is typically shut down before 5pm ET; any trigger relying on a fixed end-of-day time will be missed
- The sync must survive reboots and resume correctly with no manual recovery step
Decision¶
Implement a hybrid watcher + hourly commit + daily PR system using a macOS launchd agent.
Architecture¶
One-way sync only: real tool dirs → repo. The repo is a read-only copy.
Live configs in ~/.windsurf/ and ~/.claude/ are the source of truth and
are never overwritten by the repo.
Components¶
scripts/ai-tools-sync.py — Python worker with subcommands:
| Subcommand | Called by | What it does |
|---|---|---|
queue <file> |
watcher on every file event | Copies file to repo, adds to state queue |
commit |
timer loop every 60 min | Batch-commits all queued files in one commit |
daily-pr |
timer at 4:30pm | Creates/updates PR with today's commit timeline |
check-timers |
timer loop every 5 min | Evaluates whether hourly commit or daily PR is due |
startup |
watcher on boot | Commits pending queue + creates catch-up PR if yesterday's was missed |
status |
debugging | Prints state file as JSON |
scripts/ai-tools-watcher.sh — thin bash daemon that:
- Runs
startupon launch (catch-up from previous session) - Starts
fswatchin background with 10-second debounce; each event callsqueue - Runs a timer loop every 5 minutes calling
check-timers
scripts/install-watcher.sh — one-time installer that writes and loads a
launchd plist (com.phazeight.ai-tools-sync). The agent starts at boot and
restarts automatically if it crashes.
State persistence¶
State is persisted to ~/.local/state/ai-tools-sync.json across reboots:
{
"queue": [],
"last_hourly_commit": "2026-03-09T14:00:00",
"last_pr_date": "2026-03-08",
"commits": [
{
"time": "2026-03-09T09:15:00",
"files": ["windsurf/rules/global-coding-principles.md"]
}
]
}
Reboot / missed-trigger recovery¶
On every watcher startup:
- If
queueis non-empty → commit it now (files changed before shutdown that weren't in the last hourly batch) - If yesterday has commits but no PR → create a catch-up PR immediately,
titled with yesterday's date and a
(catch-up)suffix - Prune
commitsentries older than 7 days
This means the daily PR is eventually consistent: it will always be created, either at 4:30pm on the day it belongs to, or on the next morning startup.
Branch and PR strategy¶
- All automated commits land on the rolling
sync/tool-configsbranch - One PR stays open from
sync/tool-configs→mainat all times - PR body is regenerated on each
daily-prrun with the full commit timeline - The PR is reviewed and merged manually — the automation only proposes, never merges
Watched directories¶
~/.windsurf/rules/~/.windsurf/skills/~/.windsurf/workflows/~/.windsurf/memories/(global rules only)~/.claude/skills/~/.claude/hooks/~/.claude/rules/
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
| Commit on every file save | One commit per keystroke; history is noise with no meaningful granularity |
| Pure daily cron (no watcher) | Requires scanning all watched dirs for changes; no per-file event context; misses rapid back-and-forth edits within a day |
Single bash script (original ai-tools-sync.sh) |
No state, no batching, no timing logic — committed on every call; replaced by Python rewrite |
| Manual sync (run script when you remember) | The original behavior that caused the drift problem; human reliability is the problem being solved |
| Always-on git commit per change | High frequency, low signal; PR would accumulate hundreds of single-file commits |
| Scheduled launchd at fixed time (e.g. 10pm) | Missed on any day the laptop shuts down before that time, which is most workdays |
Consequences¶
Positive:
- Tool configs are automatically versioned with no manual steps after setup
- Hourly granularity preserves meaningful context (what changed in the morning vs. afternoon) without per-keystroke noise
- Daily PR provides a natural review checkpoint before changes land on
main - Reboot recovery ensures no changes are ever silently lost
- Python implementation is readable, testable, and easy to extend
Negative / Trade-offs:
scripts/lives onsync/tool-configs, notmain, until the PR is merged — this means a fresh clone ofmaindoes not include the sync tooling- The launchd agent requires one manual install step after cloning (
bash scripts/install-watcher.sh) - Daemon holds
sync/tool-configsas the active branch while idle; direct manual edits to the repo on that branch risk conflicting with automated commits - State file is local-only — does not sync between machines
Ongoing obligations:
- Re-run
install-watcher.shafter pulling changes to any script inscripts/ - Check
~/.local/log/ai-tools-sync.logif PRs stop appearing - When adding new tool config directories to watch, update
PATH_MAPinai-tools-sync.pyandWATCH_DIRSinai-tools-watcher.sh
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.