| name | claude-sync |
| description | Sync the user's entire Claude brain — memory files, skills, agents, CLAUDE.md rules, and settings — across machines and teammates using a shared Git repository.
Trigger this skill when the user wants to: push their Claude context to a remote, pull a teammate's context, see what's different between their local brain and the remote, merge a specific teammate's learnings into their own, onboard Claude on a new machine, or set up auto-sync. Also trigger on: /sync, "sync my claude", "push my memory", "pull team context", "share my brain", "sync to GitHub", "onboard new machine", "what's different from the team", "merge alice's context".
|
| argument-hint | [push|pull|diff|merge|init|status|watch] [--remote <url>] [--user <name>] |
| allowed-tools | ["Bash","Read","Write","Edit"] |
claude-sync
Sync the user's Claude brain across machines and teammates. Read skills/claude-sync/REFERENCE.md
before running any command — it contains the full protocol for each operation including safety
rules, conflict resolution policy, and the secrets-scrubbing contract.
What a "brain" contains
| Layer | Path (global) | Path (project) |
|---|
| Memory | ~/.claude/memory/ | .claude/memory/ |
| Skills | ~/.claude/skills/ | .claude/skills/ |
| Agents | ~/.claude/agents/ | .claude/agents/ |
| Rules | ~/.claude/CLAUDE.md | ./CLAUDE.md |
| Settings | ~/.claude/settings.json | — |
Settings are scrubbed before sync. Only permissions, hooks, theme, and model travel.
API keys, tokens, and .env files never leave the machine.
Determine intent, then act
Before running anything, identify which operation the user wants:
- First time / new machine →
init
- "push", "share", "upload my context" →
push
- "pull", "get latest", "download team context" →
pull
- "what changed", "diff", "compare" →
diff
- "merge alice", "absorb bob's learnings" →
merge <name>
- "auto-sync", "watch", "sync automatically" →
watch
- "status", "am I up to date" →
status
If intent is ambiguous, ask one clarifying question before proceeding.
Running commands
All operations delegate to skills/claude-sync/scripts/sync.sh:
~/.claude/skills/claude-sync/scripts/sync.sh <command> [args]
If the script is not yet installed (first run on a machine), guide the user through
init first, which sets up the sync repo and installs the script.
Output contract
Every operation must end with a structured summary. Use this exact format — fill in real values,
never placeholders:
┌─────────────────────────────────────────────┐
│ claude-sync — <operation> complete │
├─────────────────────────────────────────────┤
│ Memory files : <n> │
│ Skills : <n> │
│ Agents : <n> │
│ Branch : brain/<username> │
│ Remote : <host> │
│ Timestamp : <ISO-8601> │
└─────────────────────────────────────────────┘
Before modifying anything
- Show the user what will change (diff preview).
- Ask for confirmation if the operation overwrites existing files.
- Never silently delete or overwrite. Local data is authoritative unless the user explicitly
says otherwise.
Error handling
| Condition | What to do |
|---|
| Remote unreachable | Show the configured remote URL, suggest checking network |
git not installed | Link to https://git-scm.com and stop |
| Merge conflict | Show conflicting files, apply local-wins policy, explain why |
jq missing | Warn that settings merge will be skipped, proceed without it |
| Lock file exists | Show the PID, explain how to remove /tmp/claude-sync.lock |
| Empty remote | Normal on first push — explain and continue |
Reference documents
skills/claude-sync/REFERENCE.md — full protocol specificationskills/claude-sync/EXAMPLES.md — concrete walkthroughsskills/claude-sync/references/merge-strategy.md — how memory and skill merges workskills/claude-sync/references/conflict-resolution.md — conflict policy and edge casesskills/claude-sync/references/security.md — what gets scrubbed and why
