Add comprehensive sync guide for multi-machine setup
This commit is contained in:
admin
528
SYNC-GUIDE.md
Normal file
528
SYNC-GUIDE.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user