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.
04 — Tradeoffs & Limits
- **Sync is pull/push driven, not real-time.** If you're actively using both machines, changes on one machine won't be reflected on the other until the next pull. For rapid multi-machine workflows, this gap can be frustrating. - **No conflict resolution.** If the same command is edited on two machines before syncing, the later push wins — no merge, no warning. Git-style conflict resolution doesn't exist in this system. - **Enablement state lives in the manifest, not the local filesystem.** If the manifest is lost or corrupted, the per-machine enablement knowledge is gone. The local files survive; the tracking of what's enabled where doesn't. - **No validation of content.** cc-sync will sync anything in the tracked directories — if a skill file is broken, cc-sync will happily push it to all machines. - **Last sync was February 3, 2026.** The system hasn't been actively synced in over 2 months. This suggests either the workflow stabilized or the tool was superseded — worth clarifying during editing.
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.