claude-agents/SYNC-GUIDE.md

# 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