Claude Code Config Sync

A CLI tool to sync your Claude Code configuration files across multiple machines using a git-tracked repository.

How It Works

The tool uses a two-repo setup:

1. Sync repo — a git repo where your configs are stored, organized by machine hostname
2. This tool — the CLI that copies files between your local machine and the sync repo

sync-repo/
├── sync.config.json          # Machine & project registry
└── configs/
    └── MacBook-Pro/           # One folder per machine
        ├── global/
        │   ├── CLAUDE.md
        │   ├── settings.json
        │   ├── settings.local.json
        │   └── plugins/
        │       ├── installed_plugins.json
        │       └── known_marketplaces.json
        └── projects/
            ├── my-app/
            │   ├── CLAUDE.md
            │   ├── .claude/
            │   │   ├── settings.json
            │   │   └── settings.local.json
            │   └── memory/
            │       └── MEMORY.md
            └── another-project/
                └── ...

Installation

npm install -g cc-config-sync

Requires Node.js 18+.

Updating

To update to the latest version:

npm update -g cc-config-sync

Check your installed version:

cc-config-sync --version

Quick Start

# 1. Create a sync repo (or clone an existing one)
mkdir ~/claude-sync && cd ~/claude-sync && git init

# 2. Save the repo path so you never have to type --repo again
cc-config-sync config set-repo ~/claude-sync

# 3. Set up your machine (interactive)
cc-config-sync init

# 4. Pull your local configs into the sync repo
cc-config-sync pull

# 5. Check what's different
cc-config-sync status

Tip: cc-config-sync config set-repo <path> saves the repo path to ~/.cc-config-sync.json. After that, all commands just work in any terminal without additional flags. You can still override it per-command with --repo <path> or the CLAUDE_SYNC_REPO env var.

Commands

init

Interactive setup. Asks for your global config path (defaults to ~/.claude) and lets you add projects to track.

pull

Copies local config files into the sync repo. Safe — only writes to the sync repo, never touches your local files.

cc-config-sync pull                  # pull everything
cc-config-sync pull -p my-app        # pull one project
cc-config-sync pull --global-only    # pull global configs only
cc-config-sync pull --dry-run        # preview without copying
cc-config-sync pull --commit         # auto git commit after pull

push

Copies configs from the sync repo back to your local machine. Shows diffs before applying, asks for confirmation, and creates backups of any files it overwrites.

cc-config-sync push                  # push everything (interactive)
cc-config-sync push -y               # apply all without prompting
cc-config-sync push -p my-app        # push one project

status

Shows which files differ between your local machine and the sync repo.

cc-config-sync status                # summary only
cc-config-sync status -v             # include diffs
cc-config-sync status --all          # show missing-both entries

list

Lists all registered config paths and whether they exist locally.

add-project <name> <path>

Add a project to track.

cc-config-sync add-project my-app /path/to/my-app

remove-project <name>

Stop tracking a project.

cc-config-sync remove-project my-app

clean-backups

Find and delete backup files created by push.

config set-repo <path>

Save the sync repo path persistently so you don't have to pass --repo or set CLAUDE_SYNC_REPO every time.

cc-config-sync config set-repo ~/claude-sync

The path is stored in ~/.cc-config-sync.json. Resolution order (highest priority first):

1. --repo <path> flag
2. CLAUDE_SYNC_REPO env var
3. ~/.cc-config-sync.json (saved with config set-repo)
4. Error if none found

config show

Display the currently saved repo path and config file location.

cc-config-sync config show

Non-Interactive Mode

For use in CI/CD pipelines, scripts, and AI agents. Suppresses all interactive prompts.

# Via flag
cc-config-sync --non-interactive push
cc-config-sync --non-interactive init --machine-name my-machine --global-path ~/.claude

# Via CI environment variable (auto-detected)
CI=true cc-config-sync push

Behavior by command

| Command | Interactive (default) | Non-interactive | | ---------------- | ------------------------- | ----------------------------------------------------------------- | | push | Confirms each file change | Applies all changes | | init | Prompts for all values | Requires --machine-name; others use defaults or existing values | | remove-project | Asks to delete repo dir | Keeps repo dir (use --delete-repo-dir to delete) | | clean-backups | Confirms before deleting | Deletes without confirmation | | Others | No prompts | No change |

Init flags (non-interactive)

| Flag | Required | Default | | -------------------------- | -------- | -------------- | | --machine-name <name> | Yes | — | | --global-path <path> | No | ~/.claude | | --backup / --no-backup | No | --backup | | --project <name:path> | No | — (repeatable) |

Configuration

sync.config.json

The registry file in the sync repo:

{
  "machines": {
    "MacBook-Pro": {
      "globalConfigPath": "/Users/me/.claude",
      "projects": {
        "my-app": "/Users/me/projects/my-app",
        "api": "/Users/me/projects/api"
      }
    }
  }
}

What Gets Synced

Per machine, the tool tracks:

| Scope | Files | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | Global (~/.claude/) | CLAUDE.md, settings.json, settings.local.json, plugins/installed_plugins.json, plugins/known_marketplaces.json | | Per-project (project root) | CLAUDE.md, .claude/settings.json, .claude/settings.local.json | | Per-project (memory) | ~/.claude/projects/<project-id>/memory/MEMORY.md |

Typical Workflow

# On machine A — save your latest configs
cc-config-sync pull
cd ~/claude-sync && git add -A && git commit -m "update configs" && git push

# On machine B — get the latest configs
cd ~/claude-sync && git pull
cc-config-sync push

Development

git clone https://github.com/eligoss/cc-config-sync.git
cd cc-config-sync
npm install
npm test
npm run typecheck

See CONTRIBUTING.md for more details.

License

MIT