CC Sync
Claude Code Settings Sync Across Machines
Synchronizes Claude Code commands, skills, agent definitions, and rules across multiple machines — so a developer's environment is consistent everywhere, automatically.
01 — The Problem
A developer working across multiple machines (e.g., MacStudio and Mac Mini) has to manually maintain command definitions, skills, and agent configurations separately on each machine. If they add a skill on one machine, the other falls out of sync. Over time, the machines diverge — different commands, different skills, different agent configs. This creates friction and inconsistency, especially when working in Claude Code on different workstations throughout the day.
02 — What the AI Does
cc-sync is a manifest-driven synchronization system. It tracks which commands, skills, agents, and rules are enabled on which machines, and maintains a shared registry of those items in a manifest file. When items change on one machine, they get pushed to the manifest; other machines pull from it. The system tracks push/pull history, machine registration, and per-machine enablement state. Built on: JSON manifest (`manifest.json`), filesystem-based commands/skills/agents directories, git-tracked sync state.
03 — Design Decisions
Manifest-based sync over a centralized server
A JSON file in git is the simplest possible sync mechanism. No backend, no service to run, no API to manage. Git does the distributed sync work; the manifest is just a file that tracks what's where.
Real-time sync doesn't exist — you get sync when you pull/push. For a developer actively working across two machines simultaneously, this could mean one machine has stale settings while the other has new ones.
Per-machine enablement rather than global sync
Not every command/skill should be enabled on every machine. A skill that works on one OS might not work on another. The enablement map lets each machine specify what it runs, independent of other machines.
The enablement state is per-machine and tracked in the manifest. If a machine breaks or is reformatted, the enablement state is lost unless the manifest is backed up.
Filesystem-based commands/skills/agents storage
Claude Code reads from `.claude/commands/` and `.claude/skills/` natively. By storing items in those directories, cc-sync is transparent to Claude Code itself — no integration work required.
Items must be valid Claude Code command/skill/agent files. cc-sync assumes the content is valid but doesn't validate it.
Activity log for push/pull history
The manifest tracks push/pull events with timestamps and machine IDs. This creates an audit trail for "what changed when and where." Useful for debugging sync failures or understanding when a new skill was added.
The activity log grows indefinitely. There's no documented retention or cleanup policy for old activity entries.
05 — Key Insight
Synchronization systems for developer environments face a fundamental tradeoff: simplicity (file-based git sync) vs. correctness (real-time conflict resolution). The manifest approach is right for most developers; teams with complex multi-machine workflows may need something more sophisticated. The right answer depends on how often the machines are used simultaneously.