Skip to content

Automated sync of AI tool configs via hybrid watcher + daily PR

  • Date: 2026-03-09
  • Status: Superseded by 0033
  • Tags: workflow tooling process

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:

  1. Runs startup on launch (catch-up from previous session)
  2. Starts fswatch in background with 10-second debounce; each event calls queue
  3. 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:

  1. If queue is non-empty → commit it now (files changed before shutdown that weren't in the last hourly batch)
  2. If yesterday has commits but no PR → create a catch-up PR immediately, titled with yesterday's date and a (catch-up) suffix
  3. Prune commits entries 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-configs branch
  • One PR stays open from sync/tool-configs → main at all times
  • PR body is regenerated on each daily-pr run 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 on sync/tool-configs, not main, until the PR is merged — this means a fresh clone of main does not include the sync tooling
  • The launchd agent requires one manual install step after cloning (bash scripts/install-watcher.sh)
  • Daemon holds sync/tool-configs as 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.sh after pulling changes to any script in scripts/
  • Check ~/.local/log/ai-tools-sync.log if PRs stop appearing
  • When adding new tool config directories to watch, update PATH_MAP in ai-tools-sync.py and WATCH_DIRS in ai-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.