admin/claude-agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
claude-agents/SYNC-GUIDE.md

11 KiB
Raw Permalink Blame History

Claude Agent Sync Guide

Complete guide for syncing Claude Code agents across multiple machines using Gitea.

📋 Table of Contents

  1. Overview
  2. Initial Setup - Machine WITH Existing Agents
  3. Initial Setup - Machine WITHOUT Agents
  4. Daily Sync Workflow
  5. Conflict Resolution
  6. Troubleshooting
  7. 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)

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

# 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

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

# 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

# Push your agents back to the repo
git push origin main

# Verify sync
git status

Step 6: Verify All Agents Present

# 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.

Setup Without Agents

Use this if the machine has no agents or you want a fresh start.

Step 1: Configure Git (One-Time)

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

# 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

Pull Changes (Get Latest from Other Machines)

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)

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:

#!/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:

chmod +x ~/sync-agents.sh

Use it:

~/sync-agents.sh

Or add to .bashrc:

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)

# 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:

git add homelab-optimizer.md
git commit -m "Resolve conflict in homelab-optimizer"
git push origin main

Method 2: Keep Local Version

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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!

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

# 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

# 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

# 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

# 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

# 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:

# 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

Last Updated: 2026-01-29 Version: 1.0 Maintained By: admin

Reference in New Issue View Git Blame Copy Permalink