claude-sync

claude-sync

繁體中文

Early Preview — This plugin is under active development. Features may change, and you may encounter rough edges. Bug reports and feedback are welcome via GitHub Issues.

Sync your Claude Code settings, plugins, and commands across machines using any git remote.

No extra dependencies. No server. Just one private git repo.

---

📦 Install

# 1. Add the marketplace
claude plugin marketplace add chenyii1120/claude-sync

# 2. Install the plugin
claude plugin install claude-sync

# Or install directly from source (for development)
claude plugin install /path/to/claude-sync

Troubleshooting: If plugin install fails with Permission denied (publickey), this is a known Claude Code bug where plugin install forces SSH even for public repos. Run this once to fix:

git config --global url."https://github.com/".insteadOf "git@github.com:"

🚀 Quick Start

First machine:

/sync-init          # Create or connect a git repo
/sync-push          # Push your settings

Other machines:

/sync-init <url>    # Connect to the same repo
/sync-pull          # Pull settings from remote

---

🔧 Commands

/sync-init — First-time setup

Two paths depending on your environment:

Path A — Create a new GitHub repo

Default if gh CLI is available and authenticated.

1. Checks prerequisites: git (required), gh (optional)
2. Runs gh repo create claude-config-sync --private to create a private repo
3. Clones to ~/.claude/sync/repo/
4. Exports your current local settings into the repo
5. Commits and pushes
6. Saves sync config to ~/.claude/sync/config.json

Path B — Connect to an existing repo

Works with any git remote: GitHub, GitLab, Bitbucket, self-hosted, etc.

1. You provide a remote URL
2. Clones to ~/.claude/sync/repo/
3. If the repo already has sync data (i.e., a global/ directory exists), it skips the initial export — your remote settings are preserved, and you can pull them with /sync-pull
4. If the repo is empty, exports your local settings and pushes

💡 Second machine detection: When you run /sync-init on a new machine pointing to a repo that already has data, it automatically recognizes this and offers to pull immediately — no extra steps.

---

/sync-push — Export & push

Exports your local settings to the sync repo and pushes to remote.

1. 📝 Reads ~/.claude/settings.json, filters out blacklisted fields (statusLine), writes to repo/global/settings.json

2. 🔌 Reads ~/.claude/plugins/installed_plugins.json and known_marketplaces.json, transforms absolute paths → ${CLAUDE_HOME} placeholders, writes to repo/global/

3. 🔌 Copies plugin data (CLAUDE.md, blocklist.json, data/, plugin-specific config dirs) to repo/global/plugin-data/, excluding rebuildable content (cache/, marketplaces/)

4. 📂 Copies ~/.claude/commands/, ~/.claude/rules/, ~/.claude/agents/, ~/.claude/skills/, and ~/.claude/hooks/ to repo/user-config/

5. 📤 Runs git add -A && git commit && git push

6. 🔄 If push is rejected (remote has newer commits), automatically fetches, performs field-level JSON merge, then retries

---

/sync-pull — Fetch & apply

Pulls remote settings and applies them locally.

1. 💾 Auto-backup — Snapshots your current settings, plugin configs, plugin data, commands, rules, agents, skills, and hooks to ~/.claude/sync-backups/ (max 5 retained, oldest auto-pruned)

2. 📤 Export + commit local state — Exports current local ~/.claude/ state and commits to the repo before merging, so smart merge sees both sides for a correct 3-way merge

3. 🔄 Fetch + merge — If merge conflicts occur, performs field-level JSON merge with remote preference

4. ⚙️ Import settings — Merges remote settings into local settings.json. Blacklisted fields (e.g., statusLine) are preserved from local and never overwritten

5. 🔌 Import plugin configs + plugin data — Transforms ${CLAUDE_HOME} placeholders back to local absolute paths. Imports plugin data (CLAUDE.md, blocklist.json, data/, plugin-specific dirs)

6. 📂 Import commands / rules / agents / skills / hooks — Mirror syncs from repo to local directories. Files deleted on the source machine are also removed locally. Changes to rules/, skills/, and hooks/ are shown to the user with a confirmation prompt before applying (security measure — these may contain executable code)

7. 🔧 Auto plugin reinstallation — Detects missing marketplace clones and plugin installations. Automatically runs:

   • claude plugin marketplace add for each missing marketplace source
   • claude plugin update to reinstall all missing plugins

   This ensures a pull results in a fully working setup, not just config files without actual plugin code.

---