Sync your Claude Code agents, skills, and commands between global and project configurations.

Keep your Claude Code setup consistent across projects while maintaining project-specific customizations.

cargo install ccsync

curl https://i.jpillora.com/onsails/[email protected]!| bash

Note: Nix package is pending review (PR #456721)

# Once merged, install with: nix profile install nixpkgs#ccsync # Or use in a shell: nix shell nixpkgs#ccsync

# Sync your global Claude settings to current project ccsync to-local # Sync project settings back to global ccsync to-global

The tool will prompt you for each file. Press a single key:

• y - Yes, sync this file
• n - No, skip this file
• a - Yes to all remaining
• s - Skip all remaining
• d - Show me the changes first
• q - Quit

# Auto-approve everything (useful for scripts) ccsync to-local --yes-all # Preview what would change (no actual changes) ccsync to-local --dry-run

# Sync only agents ccsync to-local --type=agents # Sync only skills ccsync to-local --type=skills # Sync multiple types ccsync to-local --type=agents --type=skills

When the same file exists in both locations with different content:

# Stop and ask (default) ccsync to-local # Always overwrite with source ccsync to-local --conflict=overwrite # Skip files that have conflicts ccsync to-local --conflict=skip # Keep whichever file is newer ccsync to-local --conflict=newer

By default, ccsync asks you to approve each file before syncing:

📄 Create new file: Source: ~/.claude/agents/test.md Dest: ./.claude/agents/test.md Proceed? [y/n/a/s/d/q]: _ 

Press d to preview the file content before deciding.

Press a to approve all remaining files (no more prompts).

Press q or Ctrl+C to cancel anytime.

• Agents in ~/.claude/agents/ ↔ ./.claude/agents/
• Skills in ~/.claude/skills/ ↔ ./.claude/skills/
• Commands in ~/.claude/commands/ ↔ ./.claude/commands/

Create a .ccsync.toml file in your project to customize sync behavior:

# Ignore certain files (gitignore-style patterns)ignore = ["**/test-*.md", "**/*.backup"] # Only sync specific patternsinclude = ["agents/**", "skills/**"] # Set default conflict strategyconflict_strategy = "newer"

Config file locations (in order of precedence):

1. --config <path> - Custom config file via flag
2. .ccsync.local.toml - Project-local (gitignored, for personal settings)
3. .ccsync.toml - Project config (committed to repo)
4. ~/.config/ccsync/config.toml - Global config

CLI flags always override config files.

# Ignore all config files, use only CLI flags ccsync to-local --no-config

# See what would change (no actual sync) ccsync to-local --dry-run

# Just sync your agent definitions ccsync to-local --type=agents --yes-all

# Automatically keep whichever file was modified most recently ccsync to-local --conflict=newer --yes-all

Q: What happens if I press 'y' on a conflict?
A: The source file will overwrite the destination (or follow your --conflict strategy).

Q: Can I review all changes before applying them? A: Yes! Use ccsync to-local --dry-run to preview without making changes.

Q: What if files are already in sync?
A: You'll see Skipped: N (identical content: N) - no operations performed.

Q: How do I automate this for scripts?
A: Use ccsync to-local --yes-all to skip all prompts.

MIT