From de3ad1f8de3f7e68f736eee08a1b9329e5784ccd Mon Sep 17 00:00:00 2001
From: admin <admin@server-ai.local>
Date: Thu, 29 Jan 2026 16:16:44 +0000
Subject: [PATCH] Add comprehensive sync guide for multi-machine setup

---
 SYNC-GUIDE.md | 528 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 528 insertions(+)
 create mode 100644 SYNC-GUIDE.md

diff --git a/SYNC-GUIDE.md b/SYNC-GUIDE.md
new file mode 100644
index 0000000..3d57b5e
--- /dev/null
+++ b/SYNC-GUIDE.md
@@ -0,0 +1,528 @@
+# Claude Agent Sync Guide
+
+Complete guide for syncing Claude Code agents across multiple machines using Gitea.
+
+## 📋 Table of Contents
+
+1. [Overview](#overview)
+2. [Initial Setup - Machine WITH Existing Agents](#setup-with-existing-agents)
+3. [Initial Setup - Machine WITHOUT Agents](#setup-without-agents)
+4. [Daily Sync Workflow](#daily-sync-workflow)
+5. [Conflict Resolution](#conflict-resolution)
+6. [Troubleshooting](#troubleshooting)
+7. [Advanced Operations](#advanced-operations)
+
+---
+
+## Overview
+
+**Repository**: https://gitea.pressmess.duckdns.org/admin/claude-agents
+
+**What gets synced**: All `.md` files in `~/.claude/agents/`
+
+**How it works**: Git-based 2-way sync - all machines push and pull from central Gitea repository
+
+**Safety**: Full version history, automatic backups, conflict detection
+
+---
+
+## Setup With Existing Agents
+
+Use this if the machine already has agents in `~/.claude/agents/`.
+
+### Step 1: Configure Git (One-Time)
+
+```bash
+git config --global user.name "admin"
+git config --global user.email "admin@server-ai.local"
+git config --global init.defaultBranch main
+```
+
+### Step 2: Backup Existing Agents
+
+```bash
+# Safety first - create backup
+cp -r ~/.claude/agents ~/.claude/agents.backup-$(date +%Y%m%d-%H%M%S)
+
+# Verify backup
+ls -la ~/.claude/agents.backup-*/
+```
+
+### Step 3: Initialize Git and Commit Local Agents
+
+```bash
+cd ~/.claude/agents
+
+# Initialize git
+git init
+git checkout -b main
+
+# Commit your existing agents
+git add .
+git commit -m "Add existing agents from $(hostname) on $(date '+%Y-%m-%d')"
+```
+
+### Step 4: Connect to Gitea and Merge
+
+```bash
+# Add remote (password is URL-encoded: @ = %40, ! = %21)
+git remote add origin https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git
+
+# Pull and merge with existing agents
+git pull origin main --allow-unrelated-histories
+
+# If merge succeeds automatically, great! If not, see "Conflict Resolution" section
+```
+
+### Step 5: Push Your Unique Agents
+
+```bash
+# Push your agents back to the repo
+git push origin main
+
+# Verify sync
+git status
+```
+
+### Step 6: Verify All Agents Present
+
+```bash
+# List all agents
+ls -1 ~/.claude/agents/*.md
+
+# Check git log
+git log --oneline --graph --all
+```
+
+**✅ Done!** Your agents are now synced. Proceed to [Daily Sync Workflow](#daily-sync-workflow).
+
+---
+
+## Setup Without Agents
+
+Use this if the machine has no agents or you want a fresh start.
+
+### Step 1: Configure Git (One-Time)
+
+```bash
+git config --global user.name "admin"
+git config --global user.email "admin@server-ai.local"
+git config --global init.defaultBranch main
+```
+
+### Step 2: Clone Repository
+
+```bash
+# Remove directory if it exists (be careful!)
+# rm -rf ~/.claude/agents
+
+# Clone from Gitea (password is URL-encoded)
+git clone https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git ~/.claude/agents
+
+# Verify
+cd ~/.claude/agents
+ls -la
+git log --oneline
+```
+
+**✅ Done!** Proceed to [Daily Sync Workflow](#daily-sync-workflow).
+
+---
+
+## Daily Sync Workflow
+
+### Pull Changes (Get Latest from Other Machines)
+
+```bash
+cd ~/.claude/agents
+git pull origin main
+```
+
+**When to pull**:
+- Before starting work
+- Before creating new agents
+- At least once per day
+
+### Push Changes (Share Your Updates)
+
+```bash
+cd ~/.claude/agents
+
+# Add any new or modified agents
+git add .
+
+# Commit with descriptive message
+git commit -m "Add new agent: my-helper-agent"
+# or
+git commit -m "Update homelab-optimizer: improve recommendations"
+
+# Push to Gitea
+git push origin main
+```
+
+**When to push**:
+- After creating new agents
+- After modifying existing agents
+- Before shutting down the machine
+
+### Quick Sync Script (Recommended)
+
+Create `~/sync-agents.sh`:
+
+```bash
+#!/bin/bash
+cd ~/.claude/agents
+
+echo "📥 Pulling latest agents..."
+git pull origin main
+
+if [[ -n $(git status --porcelain) ]]; then
+    echo ""
+    echo "📝 Local changes detected:"
+    git status --short
+    echo ""
+    read -p "Commit and push changes? (y/N) " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        git add .
+        read -p "Commit message: " msg
+        git commit -m "$msg"
+        git push origin main
+        echo "✅ Changes pushed!"
+    fi
+else
+    echo "✅ Already up to date"
+fi
+
+echo ""
+echo "📊 Current agents:"
+ls -1 *.md 2>/dev/null | sed 's/\.md$//' | sed 's/^/  - /'
+```
+
+Make it executable:
+```bash
+chmod +x ~/sync-agents.sh
+```
+
+Use it:
+```bash
+~/sync-agents.sh
+```
+
+Or add to `.bashrc`:
+```bash
+alias sync-agents='~/sync-agents.sh'
+```
+
+---
+
+## Conflict Resolution
+
+### What is a Conflict?
+
+A conflict occurs when:
+- Same agent file modified on two machines
+- Both machines push changes
+- Git can't automatically merge
+
+### Identifying Conflicts
+
+After `git pull`, you'll see:
+```
+Auto-merging homelab-optimizer.md
+CONFLICT (content): Merge conflict in homelab-optimizer.md
+Automatic merge failed; fix conflicts and then commit the result.
+```
+
+### Resolving Conflicts
+
+#### Method 1: Manual Resolution (Recommended)
+
+```bash
+# Open the conflicting file
+nano ~/.claude/agents/homelab-optimizer.md
+```
+
+Look for conflict markers:
+```
+<<<<<<< HEAD
+Your local version of the agent
+=======
+Remote version from Gitea
+>>>>>>> origin/main
+```
+
+**Choose one**:
+- Keep local version (delete markers and remote version)
+- Keep remote version (delete markers and local version)
+- Combine both (merge manually, delete markers)
+
+**Then commit**:
+```bash
+git add homelab-optimizer.md
+git commit -m "Resolve conflict in homelab-optimizer"
+git push origin main
+```
+
+#### Method 2: Keep Local Version
+
+```bash
+# Keep your version for specific file
+git checkout --ours homelab-optimizer.md
+git add homelab-optimizer.md
+git commit -m "Keep local version of homelab-optimizer"
+git push origin main
+```
+
+#### Method 3: Keep Remote Version
+
+```bash
+# Keep remote version for specific file
+git checkout --theirs homelab-optimizer.md
+git add homelab-optimizer.md
+git commit -m "Accept remote version of homelab-optimizer"
+git push origin main
+```
+
+#### Method 4: Abort Merge
+
+```bash
+# Start over
+git merge --abort
+git pull origin main --strategy-option theirs  # Always prefer remote
+```
+
+### Preventing Conflicts
+
+1. **Pull before making changes**: `git pull origin main`
+2. **Push frequently**: Don't let changes accumulate
+3. **Coordinate with team**: Use chat/email when editing same agent
+4. **Use branches**: For experimental agents (advanced)
+
+---
+
+## Troubleshooting
+
+### Authentication Failed
+
+**Error**: `fatal: Authentication failed`
+
+**Solution**:
+```bash
+# Update remote with correct password (URL-encoded)
+cd ~/.claude/agents
+git remote set-url origin https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git
+```
+
+### Diverged Branches
+
+**Error**: `Your branch and 'origin/main' have diverged`
+
+**Solution**:
+```bash
+# Option 1: Rebase (cleaner history)
+git pull --rebase origin main
+
+# Option 2: Merge (safer)
+git pull origin main
+
+# Then push
+git push origin main
+```
+
+### Uncommitted Changes Blocking Pull
+
+**Error**: `error: Your local changes would be overwritten by merge`
+
+**Solution**:
+```bash
+# Option 1: Commit changes first
+git add .
+git commit -m "WIP: uncommitted changes"
+git pull origin main
+
+# Option 2: Stash changes temporarily
+git stash
+git pull origin main
+git stash pop
+```
+
+### Accidentally Deleted Agent
+
+**Recovery**:
+```bash
+# Find the commit where it existed
+git log --all --full-history -- deleted-agent.md
+
+# Restore from specific commit
+git checkout <commit-hash> -- deleted-agent.md
+
+# Or restore from last known good state
+git checkout HEAD~1 -- deleted-agent.md
+
+# Commit restoration
+git add deleted-agent.md
+git commit -m "Restore deleted-agent"
+git push origin main
+```
+
+### Reset to Remote State (Nuclear Option)
+
+**Warning**: This discards ALL local changes!
+
+```bash
+cd ~/.claude/agents
+
+# Backup first!
+cp -r ~/.claude/agents ~/agents-backup-emergency
+
+# Hard reset to remote
+git fetch origin
+git reset --hard origin/main
+```
+
+---
+
+## Advanced Operations
+
+### View History
+
+```bash
+# All commits
+git log
+
+# One line per commit
+git log --oneline
+
+# With graph
+git log --oneline --graph --all
+
+# Changes to specific agent
+git log --follow homelab-optimizer.md
+
+# See actual changes
+git log -p homelab-optimizer.md
+```
+
+### Compare Versions
+
+```bash
+# See what changed in last commit
+git show
+
+# Compare with remote
+git diff origin/main
+
+# Compare specific file
+git diff origin/main homelab-optimizer.md
+
+# Compare two commits
+git diff abc123 def456
+```
+
+### Rollback to Previous Version
+
+```bash
+# See history
+git log --oneline
+
+# Rollback entire repo to previous commit
+git reset --hard abc123
+git push -f origin main  # Force push (use with caution!)
+
+# Rollback single file
+git checkout abc123 -- homelab-optimizer.md
+git commit -m "Rollback homelab-optimizer to previous version"
+git push origin main
+```
+
+### Create Branch for Experiments
+
+```bash
+# Create and switch to new branch
+git checkout -b experiment/new-agent
+
+# Make changes, commit
+git add new-experimental-agent.md
+git commit -m "Experiment with new agent"
+
+# Push branch to Gitea
+git push -u origin experiment/new-agent
+
+# Switch back to main
+git checkout main
+
+# Merge experiment if successful
+git merge experiment/new-agent
+git push origin main
+
+# Delete branch
+git branch -d experiment/new-agent
+git push origin --delete experiment/new-agent
+```
+
+### Add More Machines
+
+Just repeat the setup process on each machine. All machines will sync through Gitea.
+
+### Change Password
+
+```bash
+# Update remote URL with new password (URL-encoded)
+cd ~/.claude/agents
+git remote set-url origin https://admin:NEW_PASSWORD@gitea.pressmess.duckdns.org/admin/claude-agents.git
+```
+
+---
+
+## Quick Reference Card
+
+### Daily Commands
+
+| Task | Command |
+|------|---------|
+| Get latest | `cd ~/.claude/agents && git pull` |
+| Push changes | `git add . && git commit -m "msg" && git push` |
+| Check status | `git status` |
+| View agents | `ls -1 ~/.claude/agents/*.md` |
+
+### Emergency Commands
+
+| Task | Command |
+|------|---------|
+| Abort merge | `git merge --abort` |
+| Discard changes | `git checkout -- filename.md` |
+| Reset to remote | `git fetch && git reset --hard origin/main` |
+
+### Useful Aliases
+
+Add to `~/.bashrc`:
+
+```bash
+# Quick sync
+alias sync-agents='cd ~/.claude/agents && git pull && git status'
+
+# Quick commit
+alias commit-agents='cd ~/.claude/agents && git add . && git commit -m'
+
+# Push agents
+alias push-agents='cd ~/.claude/agents && git push'
+
+# View agents
+alias list-agents='ls -1 ~/.claude/agents/*.md | xargs -n1 basename | sed "s/.md$//"'
+```
+
+---
+
+## Support
+
+- **Repository**: https://gitea.pressmess.duckdns.org/admin/claude-agents
+- **Local Docs**: `~/.claude/agents/README.md`
+- **Server Docs**: `/home/jon/SERVER-DOCUMENTATION.md`
+- **Changelog**: `/home/jon/CHANGELOG.md`
+
+---
+
+**Last Updated**: 2026-01-29
+**Version**: 1.0
+**Maintained By**: admin