markus41/claude-code-sync

Claude Code Sync

Updates an existing setup without blowing away user customizations. Idempotent — safe to run weekly, monthly, or on a schedule.

What sync does

1. Re-fingerprint: scan the repo for stack changes since last setup. New framework? New DB? New CI/CD tool?
2. Delta propagation: push plugin rule updates (cc-always.md, cc-patterns.md) into the repo's .claude/rules/.
3. Section-merge CLAUDE.md: update the "Build & Test", "Tech Stack", "Key Paths" sections if stack changed; leave custom sections alone.
4. Fix drift (--fix-drift flag): find config that drifted from plugin defaults — missing hooks, missing MCP servers, outdated skill versions — and repair.
5. Propagate to sub-repos: for monorepos, walk workspace children and apply changes to their .claude/ dirs.
6. Scaffold docs/context/ (if absent): create the 22-template knowledge base that complements .claude/.
7. Auto-install LSPs: detect missing LSP servers from the stack and offer install commands.
8. Persist sync state: write .claude/sync-state.json with timestamp, plugin version, delta summary.

Section-merge protocol for CLAUDE.md

CLAUDE.md sections are identified by ## headings. Sync protocol:

| Section | Action | |---|---| | ## Build & Test | Replace (regenerated from fingerprint) | | ## Tech Stack | Replace | | ## Key Paths | Replace | | ## Architecture | Preserve (user-curated) | | ## Conventions | Merge (preserve user additions, update detected items) | | ## Don't Touch | Merge (preserve user additions) | | ## Knowledge Library (Obsidian) | Replace if managed-by-plugin marker present | | Any other section | Preserve as-is |

Managed sections carry a <!-- plugin:cc-setup managed --> marker. Unmarked sections are never touched.

Drift detection (--fix-drift)

Compares current state to plugin baseline:

| Check | Fix | |---|---| | Missing .claude/rules/cc-always.md | Copy from plugin | | Missing .claude/rules/cc-obsidian-intro.md | Copy from plugin | | cc-patterns.md older than plugin's | Offer update (user confirms) | | Hook script path doesn't match registered hook | Reconcile or remove dead registration | | Settings allowlist has entries for removed tools | Prune | | MCP server in .mcp.json has no backing install | Warn | | Skills in .claude/skills/ belong to old plugin version | Offer replacement |

Never deletes user-added config. All destructive fixes require explicit confirmation.

Sub-repo propagation

For monorepos (turbo/nx/lerna/pnpm-workspaces), sync walks workspace packages and:

1. If package has its own .claude/ → sync it (same protocol as root).
2. If package has no .claude/ → create a minimal one that references the root's CLAUDE.md.
3. Generate per-package CLAUDE.md stubs for LOC > 10k packages.

docs/context/ scaffolding

If docs/context/ does not exist, create from 22 templates:

• docs/context/README.md
• docs/context/architecture/overview.md
• docs/context/architecture/modules.md
• docs/context/conventions/code-style.md
• docs/context/conventions/git-workflow.md
• docs/context/conventions/testing.md
• docs/context/decisions/0001-use-claude-code.md
• docs/context/runbooks/deploy.md
• docs/context/runbooks/rollback.md
• docs/context/glossary.md
• ... (full list via cc_kb_docs_context_templates)

Sync state file

.claude/sync-state.json:

{
  "version": "1.0",
  "last_synced": "2026-04-16T14:00:00Z",
  "plugin_version": "8.0.0",
  "stack_fingerprint": "node-ts-nextjs-postgres-prisma-jest-vercel",
  "sub_repos_synced": 0,
  "drift_fixed": ["added missing cc-obsidian-intro.md", "pruned 2 dead hook registrations"],
  "next_check_due": "2026-05-16"
}

MCP delegation

| Need | Tool | |---|---| | Hook pack recommendations after stack change | cc_docs_hook_pack_recommend(signals) | | LSP config for newly detected language | cc_kb_lsp_config(language) | | Topology for new work patterns | cc_docs_team_topology_recommend(...) |

Anti-patterns

• Running sync without reading .claude/sync-state.json → can't tell what changed since last sync.
• --fix-drift without user confirmation → destroys custom config that looks like drift.
• Syncing sub-repos without their owners' awareness → surprises.
• Re-running setup instead of sync → overwrites user customizations.

Reference

• drift-rubric.md — what counts as drift vs. valid customization