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