workbuddy-multi-machine-sync

WorkBuddy Multi-Machine Sync (3+ Devices)

Overview

Extend WorkBuddy config sync to three or more Macs. Built on top of the two-machine sync skill, this adds:

• Machine naming — each Mac gets a human-readable label (e.g. studio, laptop, office) for easy identification in commit logs
• Machine registry — a machines.json file tracks all registered machines and their last-sync timestamps
• Conflict-aware sync — more aggressive rebase + auto-resolve strategy for the higher conflict probability with 3+ machines
• Status command — wbstatus shows which machines are registered, when they last synced, and which is currently active
• Backend agnostic — works with GitHub or iCloud

When to Use This vs Two-Machine Sync

If you only have 2 machines, use workbuddy-multi-device-sync (simpler). Upgrade to this skill when adding a 3rd machine.

What Syncs vs What Doesn't

Same as the two-machine skill. Additionally:

Syncs (new)

• .machine-name — this machine's label
• machines.json — registry of all machines

Does NOT Sync (same as before)

• binaries/, workbuddy.db, .mcp.json, sessions/, logs/, traces/, credentials/, memory/, daemon state files

Workflow

Phase 1: Set Up Machine 1 (Primary)

Follow the two-machine skill (workbuddy-multi-device-sync) for Mac A setup, then add multi-machine enhancements:

Step 1: Register Machine Name

# Set a human-readable name for this machine
echo "studio" > ~/.workbuddy/.machine-name

Choose short, descriptive names: studio, laptop, office, home, etc.

Step 2: Initialize Machine Registry

# Create machines.json with this machine registered
MACHINE_NAME=$(cat ~/.workbuddy/.machine-name)
HOSTNAME=$(hostname)
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

cat > ~/.workbuddy/machines.json << EOF
{
  "machines": [
    {
      "name": "$MACHINE_NAME",
      "hostname": "$HOSTNAME",
      "registered": "$TIMESTAMP",
      "last_sync": "$TIMESTAMP",
      "status": "active"
    }
  ]
}
EOF

Step 3: Install Multi-Machine Auto-Sync

1. Copy scripts/auto-sync-multi.sh to ~/.workbuddy/auto-sync.sh
2. Copy scripts/start-sync-daemon.sh to ~/.workbuddy/start-sync-daemon.sh
3. Copy scripts/machine-status.sh to ~/.workbuddy/machine-status.sh
4. Make all executable:

chmod +x ~/.workbuddy/auto-sync.sh ~/.workbuddy/start-sync-daemon.sh ~/.workbuddy/machine-status.sh

The auto-sync-multi.sh script differs from the two-machine version:

• Tags each commit with machine name: auto-sync from
• Updates machines.json with last_sync timestamp on each sync
• Auto-resolves non-conflicting changes (accept theirs for non-overlapping files)
• Handles rebase failures gracefully (stashes, pulls, pops)

Step 4: Add Terminal Hooks

Append to ~/.bash_profile (or ~/.zshrc):

# WorkBuddy multi-machine sync shortcuts
alias wbsync='cd ~/.workbuddy && git add -A && git commit -m "sync $(date +%m%d-%H%M) from $(cat ~/.workbuddy/.machine-name 2>/dev/null || echo $(hostname))" && git push origin main'
alias wbpull='cd ~/.workbuddy && git pull --rebase origin main'
alias wbstatus='bash ~/.workbuddy/machine-status.sh'

# WorkBuddy auto-sync — daemon keepalive + sync on terminal open
if [ -f ~/.workbuddy/start-sync-daemon.sh ]; then
  bash ~/.workbuddy/start-sync-daemon.sh 2>/dev/null
fi
if [ -t 1 ] && [ -f ~/.workbuddy/auto-sync.sh ]; then
  _wb_now=$(date +%s)
  _wb_last=$(cat ~/.workbuddy/.last-auto-sync 2>/dev/null || echo 0)
  if [ $((_wb_now - _wb_last)) -gt 300 ]; then
    bash ~/.workbuddy/auto-sync.sh >/dev/null 2>&1 &
    echo $_wb_now > ~/.workbuddy/.last-auto-sync
  fi
  unset _wb_now _wb_last
fi

Step 5: Update .gitignore

Ensure these are NOT in .gitignore (they should be synced):

• .machine-name — machine label
• machines.json — machine registry

Ensure these ARE in .gitignore (already covered by template):

• .auto-sync.log, .sync-daemon.pid, .last-auto-sync, start-sync-daemon.sh

Step 6: Commit and Push

cd ~/.workbuddy
git add -A
git commit -m "init: multi-machine sync setup on $(cat .machine-name)"
git push origin main

Phase 2: Add Machine 2, 3, 4...

For each additional machine:

Prerequisites

• WorkBuddy installed and launched once, then quit
• GitHub repo accessible (or iCloud Drive synced)

Setup

Use scripts/setup-machine.sh.template as the setup script. Replace:

• `` → GitHub repo URL or iCloud bare repo path
• `` → origin for GitHub, icloud for iCloud
• / → only for GitHub backend

Then on the new machine:

# For GitHub backend:
curl -sSL -H "Authorization: token " \
  "https://raw.githubusercontent.com//wb-sync/main/wb-setup-machine.sh" | bash

# For iCloud backend:
bash wb-setup-machine.sh  # after AirDrop or manual copy

The setup script will:

1. Ask for a machine name (or accept a default based on hostname)
2. Back up existing config
3. Pull from remote
4. Register itself in machines.json
5. Install auto-sync daemon
6. Start syncing

Phase 3: Daily Usage

# Check status of all machines
wbstatus

# Output example:
# ┌──────────┬──────────────────────┬──────────┬─────────────────────┐
# │ Machine  │ Hostname             │ Status   │ Last Sync           │
# ├──────────┼──────────────────────┼──────────┼─────────────────────┤
# │ studio   │ pascalliu-mac-studio │ active   │ 2026-08-01 12:30:15 │
# │ laptop   │ pascalliu-mbp        │ active   │ 2026-08-01 12:28:42 │
# │ office   │ pascalliu-imac       │ stale    │ 2026-07-30 18:15:00 │
# └──────────┴──────────────────────┴──────────┴─────────────────────┘

• active: synced within the last 30 minutes
• stale: last sync > 30 minutes ago (machine may be offline)
• offline: last sync > 24 hours ago

Conflict Handling

With 3+ machines, conflicts are more likely. The auto-sync script uses this strategy:

1. git pull --rebase — replays local commits on top of remote
2. If rebase fails (conflicting changes to the same file):
   • Stash local changes
   • Pull (accept remote)
   • Pop stash (attempt merge)
   • If merge fails: keep remote version, log the conflict
3. Conflict log: conflicts are logged to ~/.workbuddy/.sync-conflicts.log for manual review

Resolving Conflicts Manually

cd ~/.workbuddy
git status                    # see conflicted files
# edit files to resolve...
git add -A
git rebase --continue
git push origin main

Machine Registry Format

machines.json:

{
  "machines": [
    {
      "name": "studio",
      "hostname": "pascalliu-mac-studio",
      "registered": "2026-08-01T00:00:00Z",
      "last_sync": "2026-08-01T12:30:15Z",
      "status": "active"
    },
    {
      "name": "laptop",
      "hostname": "pascalliu-mbp",
      "registered": "2026-08-01T01:00:00Z",
      "last_sync": "2026-08-01T12:28:42Z",
      "status": "active"
    }
  ]
}

Each machine updates its own entry on every sync. Stale entries (machines not seen for > 30 days) can be cleaned up manually.

Important Notes

• Only one machine should be actively used at a time for best results. The daemon handles concurrent sync, but real-time simultaneous editing of the same config files will cause conflicts.
• Machine names must be unique. If two machines have the same name, the registry will show duplicate entries.
• Automations (scheduled tasks) do NOT sync. Set them up on each machine.
• GitHub SSH port 22 may be blocked in China. Use HTTPS + token.
• LaunchAgent fails under sandbox. Use the Python daemon approach.
• Daemon recovery: After reboot, opens terminal or WorkBuddy bash command to restart daemon.

Resources

scripts/

• auto-sync-multi.sh — Enhanced sync script with machine tagging and conflict handling
• start-sync-daemon.sh — Daemon launcher (same as two-machine version)
• machine-status.sh — Display registered machines and their sync status
• setup-machine.sh.template — Setup script template for any new machine (Nth machine)

references/

• gitignore-template — .gitignore for multi-machine setup
• multi-machine-architecture.md — Architecture, conflict handling, and migration guide