Sincronizar la configuración de Claude Code (CLAUDE.md, skills, plugins, MCP) entre varios equipos con cclayer, con identidad de git separada por equipo de trabajo

Después de usar Claude Code un tiempo, en ~/.claude se acumulan bastantes cosas: el CLAUDE.md global, varias rules, skills, hooks, los permisos y plugins de settings.json y un montón de servidores MCP. Yo uso Claude Code en varios ordenadores y en cada uno tenía que configurarlo todo de nuevo. Si cambiaba una regla en uno, tenía que cambiarla a mano en los demás, y con el tiempo las configuraciones dejaban de coincidir.

Lo más molesto es que mis proyectos vienen de equipos distintos. Cada equipo tiene su propia identidad de git (nombre, correo), y algunos tienen además sus propias reglas y hooks. Todo eso solo debe aplicarse en los proyectos de ese equipo, no colarse en otros proyectos, y mucho menos acabar con el correo de la empresa en los commits de mis propios repositorios de código abierto.

Meter ~/.claude tal cual en un repositorio git tampoco sirve: ahí están el estado de sesión iniciada, el historial de sesiones y los permisos locales, y lo de cada equipo no puede ir en un repositorio público. Por eso escribí cclayer, justo para resolver esto.

Qué es cclayer

cclayer divide la configuración de Claude Code en dos tipos de «capas»:

• Capa base: lo que es igual en todos los ordenadores: CLAUDE.md, rules/, skills/, output-styles/, agents/, scripts de hooks, las claves compartidas de settings.json, la lista de plugins y marketplaces y las definiciones MCP. No contiene ninguna información de identidad, así que puede ir en un repositorio público.
• Capa de superposición: una por equipo de trabajo. Contiene la identidad de git del equipo, sus hooks, las reglas de direcciones de repositorio (por ejemplo github.com/acme-inc/*) y los .claude/settings.local.json y CLAUDE.local.md que se escriben en esos proyectos. Una capa de superposición solo actúa en los proyectos que coinciden y no escribe nada en ~/.claude.

Cada ordenador solo descarga la capa base y las superposiciones que necesita. cclayer apply lo deja todo en su sitio con un comando, y cclayer push sube los cambios locales con otro.

Una capa puede ser un repositorio git o simplemente un directorio dentro de una carpeta sincronizada en la nube, así que también se puede usar sin tocar git.

Instalación

En macOS con Homebrew:

1
brew install --cask zhaojiannet/tap/cclayer

Para actualizar más adelante:

1
brew upgrade --cask cclayer

Para Linux y Windows, descarga el binario desde la página de Releases. Hace falta tener git instalado; los pasos de plugins y MCP requieren Claude Code 2.1.288 o superior.

El caso más sencillo: una persona, varios ordenadores

Si no hay equipos que separar, basta con una capa base.

El primer ordenador

1
cclayer setup

setup es una interfaz de configuración a pantalla completa. La columna izquierda muestra las capas y los ajustes locales, y la derecha la descripción del elemento seleccionado y los campos que se pueden cambiar. No se escribe ningún archivo hasta que guardas. La interfaz está en chino simplificado, inglés y japonés, y por defecto sigue el idioma del sistema.

Solo hay que rellenar dos campos:

1. Capa base: un directorio (por ejemplo ~/Dropbox/cclayer/base en la nube) o la dirección de un repositorio git privado. Si el directorio todavía no existe, al guardar se genera automáticamente un layer.toml inicial.
2. Directorio de proyectos: donde tienes el código, por ejemplo ~/Projects.

Elige «Save and apply» y luego mete en la capa la configuración que ya tiene este ordenador:

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

Las rutas son relativas a ~/.claude. Antes de añadir cada archivo se revisa: claves, direcciones de correo o rutas absolutas que apuntan al directorio personal de esta máquina se bloquean, y te dice en qué línea están. Si la capa es solo para ti y está guardada en un sitio privado, añade la línea private = true debajo de [layer] en layer.toml y dejará de bloquear los correos.

Los demás ordenadores

Instala cclayer, ejecuta también cclayer setup, pon la misma dirección en la capa base, guarda y aplica, y ya tienes la configuración del primer ordenador. Los archivos que ya existen en local con otro contenido aparecen en una lista y te pregunta si quieres sobrescribirlos. Antes de sobrescribir, los archivos antiguos se guardan como copia en ~/.local/state/cclayer/backups/.

Sincronización diaria

Si la capa es un repositorio git:

1
cclayer push          # Subir: recoge los cambios locales, muestra lo que se va a commitear y, tras confirmar, hace commit y push
2
cclayer apply --pull  # Bajar: trae las capas más recientes y las aplica en local

Si la capa es un directorio en la nube, la sincronización la hace el servicio de almacenamiento. Después de cambiar algo ejecuta cclayer capture, y en el otro ordenador cclayer apply.

También puedes poner este hook SessionStart en el claude/settings.json de la capa base y activar «Auto pull» en setup. Así, cada vez que abras una sesión de Claude Code se descargará y aplicará todo automáticamente:

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
}

Una identidad de git distinta para cada equipo

Este es el motivo principal por el que escribí cclayer. Primero crea un repositorio privado para el equipo y pon en la raíz un layer.toml con la identidad y los repositorios que debe abarcar:

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/*"

Después, en los ordenadores que lo necesiten, añade esta capa de superposición. Te preguntará cómo configurar las credenciales de acceso al repositorio, lo clonará y lo revisará:

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

Tras apply, cclayer añade un bloque include al final de ~/.gitconfig y, con el includeIf "hasconfig:remote.*.url:..." de git, hace que esta identidad solo se aplique en repositorios cuya dirección remota coincida con github.com/acme-inc/*. El contenido que ya tenías en ~/.gitconfig no se toca. Si dejas vacía la identidad por defecto (default_identity), git se negará a hacer commit en los repositorios que no coincidan con ninguna superposición, así que ya no vuelve a pasar eso de commitear con el correo equivocado.

Las reglas de coincidencia tienen que indicar explícitamente el host y la organización, sin sustituirlos por comodines, para que la superposición de un equipo no se quede con los repositorios de otro.

Si además quieres separar por completo el inicio de sesión, las sesiones y el historial de prompts de Claude Code de cada equipo, puedes activar el modo profiles. Cada capa de superposición tendrá su propio directorio de configuración ~/.claude-profiles/<nombre de la capa>, cclayer env muestra el CLAUDE_CONFIG_DIR correspondiente y, junto con direnv, cada proyecto usa automáticamente su propia configuración.

Seguridad

Los hooks y skills sincronizados los ejecuta Claude Code en local, así que cclayer es bastante prudente en este punto:

• Los ajustes que ejecutan programas o activan plugins, como hooks, statusLine o enabledPlugins, junto con los archivos de hooks/ y skills/ y los archivos con permiso de ejecución, se muestran antes de escribirse para que los confirmes. Un contenido ya confirmado no se vuelve a preguntar.
• De los fragmentos de configuración de git solo se aceptan ajustes habituales como pull.rebase o push.default. Las claves que pueden ejecutar programas, como los alias, core.hooksPath o credential.helper, solo funcionan si marcas explícitamente esa capa como de confianza en la lista de dispositivos.
• El estado de sesión de Claude Code, history.jsonl y projects/ nunca se leen dentro de una capa, y permissions.allow y env se quedan en la máquina local.
• No se permiten enlaces simbólicos dentro de las capas, y al escribir archivos tampoco se siguen.

Comandos habituales

Para un uso más detallado, incluida la creación de los repositorios git, las credenciales de repositorios privados y las preguntas frecuentes, consulta el tutorial de cclayer (en inglés).

Proyecto en GitHub: https://github.com/zhaojiannet/cclayer