claude-code-config-sync

Claude Code Config Sync

Sync your Claude Code configuration across all your machines using Git

What It Does

Sync your Claude Code configuration across all machines automatically.

Syncs 7 essential config types:

• CLAUDE.md - Global instructions
• settings.json - User preferences
• commands/ - Custom slash commands
• agents/ - Custom subagents
• hooks/ - Lifecycle hooks
• statusline/ - Status bar configs
• .mcp.json - MCP server connections

Intelligently handles conflicts when configs differ between machines with grouped analysis and detailed review options.

Auto-excludes sensitive files: *.local.md, *.local.json, credentials, API keys, logs, history

Installation

Quick Install:

npm install -g claude-code-config-sync
claude mcp add claude-code-config-sync claude-code-config-sync --scope user

Then restart Claude Code to activate the MCP tools.

Upgrade:

npm install -g claude-code-config-sync@latest
claude mcp remove claude-code-config-sync --scope user
claude mcp add claude-code-config-sync claude-code-config-sync --scope user

Then restart Claude Code.

Manual installation (alternative)

Step 1: Install the package

npm install -g claude-code-config-sync

Step 2: Add to ~/.claude.json

Add the following to the mcpServers section:

{
  "mcpServers": {
    "claude-code-config-sync": {
      "type": "stdio",
      "command": "claude-code-config-sync",
      "args": [],
      "env": {}
    }
  }
}

Step 3: Restart Claude Code

Usage

Via Claude Code MCP tools:

sync_init    # Connect to your Git repo (auto-creates if needed)
sync_push    # Push local changes
sync_pull    # Pull remote changes
sync_status  # Check sync status

First Machine

sync_init(
  repoUrl: "claude-config",  // Auto-detects SSH or HTTPS
  autoCreate: true  // Creates private repo if missing
)
// Or use full URL: "[e-mail]:you/claude-config.git"
// Or use HTTPS: "https://github.com/you/claude-config.git"

Note: The tool automatically detects SSH availability and falls back to HTTPS when SSH keys are not configured.

Additional Machines

Simple case (no local config):

sync_init(repoUrl: "claude-config")
// Automatically pulls existing config
// Uses SSH if available, HTTPS otherwise

With existing local config (Intelligent Merge):

// Step 1: High-level analysis (grouped by type)
sync_init(repoUrl: "claude-config")

// Returns:
// 🔄 Merge Conflict Analysis
// Your local and remote configurations have differences that need resolution:
// 6 items differ across 2 configuration types.
//
// 📝 CLAUDE.md
//   1 different between local and remote, 3 only on this device, 1 only in remote
//   → Will merge all unique items from both configs
//
// 📂 Commands
//   2 different between local and remote, 8 only on this device, 2 only in remote
//   → Will create duplicate files (2 local + 2 remote versions)
//
// 🎯 Resolution Options:
// 1. Quick merge: Accept all recommendations
//    sync_init(confirmMerge: true)
// 2. Detailed review: See specific conflicts
//    sync_init(detailedReview: true)

// Step 2 (Optional): View detailed conflicts with side-by-side comparison
sync_init(repoUrl: "claude-config", detailedReview: true)

// Shows side-by-side content comparison for each conflict

// Step 3: Apply intelligent merge
sync_init(repoUrl: "claude-config", confirmMerge: true)

// ✓ Backed up original to ~/.claude-backup-2025-10-12
// ✓ Merged configurations intelligently
// ✓ Ready to sync

Common Scenarios

Daily workflow:

// Make changes to your CLAUDE.md or commands/
sync_push()  // Pushes to remote (auto-pulls if needed)

On another machine:

sync_pull()  // Gets latest changes

Check what's changed:

sync_status()  // Shows uncommitted files and sync state

Merge conflict resolution:

// If sync_init shows conflicts:
sync_init(detailedReview: true)  // See what's different
sync_init(confirmMerge: true)     // Accept and merge

See USAGE.md for detailed guide.

Key Features

🔍 Intelligent Merge with Detailed Guidance

When local and remote configs both exist, you get:

• Grouped analysis by config type (CLAUDE.md, commands/, agents/, hooks/, settings, MCP)
• Conflict counts showing local-only, remote-only, and modified items
• Recommended strategies for each config type with explanations
• Optional detailed review with side-by-side content comparison
• Automatic backup before any merge operation

🔒 Smart Conflict Detection

• Push protection: Prevents pushing when you're behind remote and modifying the same files
• Auto-pull: Automatically pulls non-conflicting changes before push
• File-level analysis: Detects conflicts at individual file level, not just branch-level

🚀 Zero-Config Workflow

• Auto-creates private GitHub repos via gh CLI
• Auto-detects SSH vs HTTPS based on your Git configuration
• Auto-excludes sensitive files (credentials, logs, local-only configs)
• Auto-generates appropriate .gitignore for Claude Code configs

📊 Full Visibility

• See exactly what's different between machines before merging
• View side-by-side comparisons of conflicting content
• Check sync status anytime to see uncommitted changes and drift

How It Works

• Init: Creates Git repo in ~/.claude with smart .gitignore, analyses any existing local/remote configs
• Push: Auto-pulls if behind, detects file-level conflicts, commits and pushes
• Pull: Fetches and merges updates from other machines safely
• Status: Shows what's changed locally and sync state with remote

Security

✅ Uses your existing Git SSH keys ✅ Auto-excludes sensitive files ✅ Never syncs credentials or API keys ✅ Private repos recommended

Links

• NPM: npmjs.com/package/claude-code-config-sync
• GitHub: github.com/jesse-windebank/claude-code-config-sync
• Issues: Report a bug

Development

git clone https://github.com/jesse-windebank/claude-code-config-sync
cd claude-code-config-sync
npm install
npm run build
npm test

License

MIT - Made for the Claude Code community

Future (v2.0)

• Templates for machine-specific configs
• Secret management (Bitwarden, 1Password)
• Auto-sync on changes

Inspired by chezmoi