Synchroniser la configuration de Claude Code (CLAUDE.md, skills, plugins, MCP) entre plusieurs machines avec cclayer, avec une identité git séparée par équipe

Au bout d’un moment avec Claude Code, pas mal de choses s’accumulent dans ~/.claude : le CLAUDE.md global, diverses rules, des skills, des hooks, les permissions et plugins dans settings.json, et toute une série de serveurs MCP. J’utilise Claude Code sur plusieurs ordinateurs, et sur chacun il fallait tout reconfigurer. Si je modifiais une règle sur une machine, je devais la reporter à la main sur les autres, et avec le temps les configurations finissaient par ne plus correspondre.

Le plus pénible, c’est que mes projets viennent d’équipes différentes. Chaque équipe a sa propre identité git (nom, e-mail), certaines ont aussi leurs propres règles et hooks. Tout ça ne doit s’appliquer qu’aux projets de l’équipe concernée, ne pas déborder sur les autres projets, et surtout il ne faut pas qu’un e-mail professionnel se retrouve dans les commits de mes propres dépôts open source.

Mettre simplement ~/.claude dans un dépôt git ne marche pas non plus : il contient l’état de connexion, l’historique des sessions et les permissions locales, et les éléments propres à une équipe ne peuvent pas aller dans un dépôt public. J’ai donc écrit cclayer pour régler précisément ce problème.

Qu’est-ce que cclayer

cclayer découpe la configuration de Claude Code en deux types de « couches » :

• Couche de base : ce qui est identique sur toutes les machines, CLAUDE.md, rules/, skills/, output-styles/, agents/, les scripts de hook, les clés partagées de settings.json, la liste des plugins et marketplaces, les définitions MCP. Elle ne contient aucune information d’identité et peut donc aller dans un dépôt public.
• Couche de surcharge : une par équipe. Elle contient l’identité git de l’équipe, ses hooks, les règles d’adresse de dépôt (par exemple github.com/acme-inc/*), ainsi que les fichiers .claude/settings.local.json et CLAUDE.local.md à écrire dans ces projets. Une couche de surcharge ne s’applique qu’aux projets correspondants et n’écrit rien dans ~/.claude.

Chaque machine ne récupère que la couche de base et les surcharges dont elle a besoin. cclayer apply met tout en place en une commande, cclayer push renvoie les modifications locales en une commande.

Une couche peut être un dépôt git, ou simplement un répertoire dans un dossier synchronisé par un stockage cloud. On peut donc s’en servir sans toucher à git.

Installation

Sous macOS avec Homebrew :

1
brew install --cask zhaojiannet/tap/cclayer

Pour mettre à jour plus tard :

1
brew upgrade --cask cclayer

Sous Linux et Windows, les binaires sont sur la page Releases. Il faut avoir git installé ; les étapes concernant les plugins et MCP demandent Claude Code 2.1.288 ou plus récent.

Le cas le plus simple : une personne, plusieurs machines

S’il n’y a pas d’équipes à séparer, une couche de base suffit.

Première machine

1
cclayer setup

setup est une interface de configuration en plein écran. La colonne de gauche liste les couches et les réglages locaux, celle de droite affiche la description de l’élément sélectionné et les champs modifiables. Aucun fichier n’est écrit tant qu’on n’a pas enregistré. L’interface est disponible en chinois simplifié, anglais et japonais, et suit par défaut la langue du système.

Il n’y a que deux champs à remplir :

1. Couche de base : un répertoire (par exemple ~/Dropbox/cclayer/base dans le stockage cloud) ou l’adresse d’un dépôt git privé. Si le répertoire n’existe pas encore, un layer.toml de départ est généré automatiquement à l’enregistrement.
2. Répertoire des projets : le répertoire où se trouve le code, par exemple ~/Projects.

Choisir « Save and apply », puis faire entrer la configuration existante de cette machine dans la couche :

1
cclayer capture --add CLAUDE.md --add rules/ --add skills/

Les chemins sont relatifs à ~/.claude. Chaque fichier est vérifié avant d’être ajouté : clés secrètes, adresses e-mail ou chemins absolus pointant vers le répertoire personnel local sont bloqués, et l’outil indique la ligne concernée. Si la couche ne sert qu’à vous et qu’elle est stockée dans un endroit privé, ajoutez la ligne private = true sous [layer] dans layer.toml, et les e-mails ne seront plus bloqués.

Les autres machines

Installer cclayer, lancer aussi cclayer setup, indiquer la même adresse pour la couche de base, enregistrer et appliquer : la configuration de la première machine arrive. Les fichiers qui existent déjà localement avec un contenu différent sont listés, et on vous demande s’il faut les écraser. Avant l’écrasement, les anciens fichiers sont sauvegardés dans ~/.local/state/cclayer/backups/.

Synchronisation au quotidien

Si la couche est un dépôt git :

1
cclayer push          # Envoi : collecte les modifications locales, liste ce qui sera commité, commit et push après confirmation
2
cclayer apply --pull  # Réception : récupère les dernières couches puis les applique localement

Si la couche est un répertoire de stockage cloud, c’est le service cloud qui synchronise. Après une modification, lancer cclayer capture, puis cclayer apply sur l’autre machine, et c’est tout.

On peut aussi mettre le hook SessionStart ci-dessous dans le claude/settings.json de la couche de base et activer « Auto pull » dans setup. À chaque ouverture d’une session Claude Code, les couches sont alors récupérées et appliquées automatiquement :

1
{
2
  "hooks": {
3
    "SessionStart": [{
4
      "matcher": "startup",
5
      "hooks": [{ "type": "command", "command": "command -v cclayer >/dev/null && cclayer apply --hook || true" }]
6
    }]
7
  }
8
}

Une identité git différente pour chaque équipe

C’est la raison principale pour laquelle j’ai écrit cclayer. On commence par créer un dépôt privé pour l’équipe, avec à la racine un layer.toml qui indique l’identité et les dépôts concernés :

1
[layer]
2
name = "acme"
3
kind = "overlay"
4

5
[identity]
6
name = "Full Name"
7
email = "me@acme.example"
8

9
[[match]]
10
remote = "github.com/acme-inc/*"

Ensuite, sur les machines qui en ont besoin, on ajoute cette couche de surcharge. cclayer demande comment configurer les identifiants d’accès au dépôt, le clone puis le vérifie :

1
cclayer layer add acme git@github.com:you/cclayer-acme.git

Après apply, cclayer ajoute un bloc include à la fin de ~/.gitconfig. Grâce au includeIf "hasconfig:remote.*.url:..." de git, cette identité ne s’applique qu’aux dépôts dont l’adresse distante correspond à github.com/acme-inc/*. Le contenu existant de ~/.gitconfig n’est jamais modifié. Si l’identité par défaut (default_identity) est laissée vide, git refuse de commiter dans les dépôts qui ne correspondent à aucune surcharge, et on ne commite plus jamais avec le mauvais e-mail.

Les règles de correspondance doivent indiquer explicitement l’hôte et l’organisation, sans les remplacer par des jokers, pour éviter que la surcharge d’une équipe s’approprie les dépôts d’une autre.

Si vous voulez aussi séparer complètement la connexion, les sessions et l’historique des prompts de Claude Code par équipe, vous pouvez activer le mode profiles. Chaque couche de surcharge a alors son propre répertoire de configuration ~/.claude-profiles/<nom de la couche>, cclayer env affiche le CLAUDE_CONFIG_DIR correspondant, et avec direnv chaque projet utilise automatiquement la bonne configuration.

Côté sécurité

Les hooks et skills synchronisés sont exécutés localement par Claude Code, donc cclayer est assez prudent sur ce point :

• Les réglages qui exécutent des programmes ou activent des plugins, comme hooks, statusLine ou enabledPlugins, ainsi que les fichiers sous hooks/ et skills/ et les fichiers exécutables, sont affichés avant écriture pour que vous confirmiez. Un contenu déjà confirmé n’est pas redemandé.
• Pour les fragments de configuration git, seuls les réglages courants comme pull.rebase ou push.default passent. Les clés capables d’exécuter des programmes, comme les alias, core.hooksPath ou credential.helper, ne sont acceptées que si la couche est explicitement marquée comme fiable dans la liste des appareils.
• L’état de connexion de Claude Code, history.jsonl et projects/ ne sont jamais lus dans une couche, et permissions.allow et env restent sur la machine locale.
• Les liens symboliques sont interdits dans les couches, et ils ne sont jamais suivis lors de l’écriture des fichiers.

Commandes courantes

Pour une utilisation plus détaillée, y compris la création des dépôts git, les identifiants pour les dépôts privés et les questions fréquentes, voir le tutoriel cclayer (en anglais).

Projet GitHub : https://github.com/zhaojiannet/cclayer