feat(scripts): auto-sync — real-time bidirectional git sync per repo

[abdout]

Summary

A background service that keeps every databayt repo at ~/<name> continuously synced with GitHub. Local commits push within ~2s; remote commits pull within ~60s. No manual git push/git pull for the common case.

Implements the "Real-time (file watcher)" sync model — the option you picked in the design question.

How it works

                    ┌─────────────────────────────┐
                    │     FileSystemWatcher /     │      Local commit
   .git/refs/heads ─┤        fswatch /            ├─►   debounce 2s
                    │       inotifywait           │      git push
                    └─────────────────────────────┘

                    ┌─────────────────────────────┐
                    │      Polling loop           │      Every 60s:
                    │      every PollInterval     ├─►   git fetch
                    │                             │      git pull --rebase
                    └─────────────────────────────┘      (skipped if dirty)

Per-repo isolation — one repo failing (no upstream, auth broken, force-push) never stops the others. Each iteration catches its own exceptions.

Working-tree-sacred — if git status --porcelain shows changes, the pull is skipped. Your in-flight work is never touched.

Conflict-safe pull — git pull --rebase fails → git rebase --abort → log error → next cycle tries again.

Files added

File	Purpose	LOC
.claude/scripts/auto-sync.ps1	Windows runtime — FileSystemWatcher + polling loop	193
.claude/scripts/auto-sync.sh	macOS/Linux runtime — fswatch / inotifywait + polling	171
.claude/scripts/auto-sync-install.ps1	Register as logon-triggered Task Scheduler task	110
.claude/scripts/auto-sync-install.sh	Register as launchd LaunchAgent (mac) / systemd user unit (linux)	143
content/docs/auto-sync.mdx	User-facing doc	140

Total: 757 lines added across 5 new files, zero existing files modified.

Install (user-scoped, no admin/sudo)

# Windows — Task Scheduler "At logon", restarts on failure 3×
& "$env:USERPROFILE\.claude\scripts\auto-sync-install.ps1" -Install

# macOS — launchd LaunchAgent with KeepAlive=true
~/.claude/scripts/auto-sync-install.sh --install

# Linux — systemd user service with Restart=always
~/.claude/scripts/auto-sync-install.sh --install

Configuration (flags)

Flag	Default	What it does
-PollInterval / --poll-interval	60s	How often to fetch+pull each repo
-Debounce / --debounce	2s	How long after a local commit before pushing
-DryRun / --dry-run	off	Log only, no actual git operations
-Once / --once	off	Exit after one poll cycle (for testing)
-Verbose / --verbose	off	Echo every log line to console

Logs

Format: [HH:MM:SS] [LEVEL] [repo-name ] message

Stored at ~/.claude/logs/auto-sync-<date>.log. Levels: INFO, PUSH, PULL, WARN, ERROR.

What it does NOT do

• Doesn't commit for you — only pushes existing commits
• Doesn't resolve conflicts — aborts the rebase and logs
• Doesn't force-push (history rewrites need manual handling)
• Doesn't touch branches other than the currently-checked-out one

The doc page has a "what auto-sync does NOT do" section that's explicit about this — auto-sync is a co-pilot for the linear-commit common case, not a magic merger.

Relationship to maintain

maintain runs once daily at 09:00 (full doctor + sync-repos burst). auto-sync runs continuously between maintain runs. Run both — they complement each other.

Test plan

• PowerShell parse-check: [PSParser]::Tokenize clean on both scripts
• Bash syntax check: bash -n clean on both scripts
• Live: install on Windows, make a commit in ~/kun, see PUSH log within ~5s
• Live: push a commit to a repo from another machine, see PULL log within ~70s on this machine
• Live: install on macOS via launchd, verify launchctl list shows the agent
• Live: install on Linux via systemd user, verify systemctl --user status kun-auto-sync shows active
• Dirty-tree case: make uncommitted changes, push from elsewhere, verify WARN + skip
• Conflict case: induce a rebase conflict, verify abort + log + retry behavior
• Auth-failure case: revoke gh auth, verify WARN per push attempt, no crash

Dependencies

Targets main directly. No dependency on the bootstrap chain (PRs 29-36, 37, 38). Works with both ~/oss/<name> (current main) and ~/<name> (PR #38) layouts — reads ~/.claude/memory/repositories.json first, falls back to canonical list otherwise.

Why this completes the "auto-synced" requirement

The user requirement was: "I expect all databayt org repos to be in the root and synced with github with auto synced." PR #38 puts them at root. This PR makes them auto-synced. Together they fulfill the requirement for every teammate.

Refs #28

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
kun	Ready	Preview, Comment	May 18, 2026 5:46am