Sincronizar a configuração do Claude Code (CLAUDE.md, skills, plugins, MCP) entre vários computadores com o cclayer, com identidade git separada por equipe

Depois de usar o Claude Code por um tempo, muita coisa vai se acumulando em ~/.claude: o CLAUDE.md global, várias rules, skills, hooks, as permissões e plugins no settings.json e um monte de servidores MCP. Eu uso o Claude Code em vários computadores, e em cada um precisava configurar tudo de novo. Se mudava uma regra em um, tinha que mudar na mão nos outros, e com o tempo as configurações deixavam de bater.

O pior é que meus projetos vêm de equipes diferentes. Cada equipe tem sua própria identidade git (nome, e-mail), e algumas têm também regras e hooks próprios. Isso tudo só deve valer nos projetos daquela equipe, sem vazar para outros projetos, e muito menos pode acontecer de o e-mail da empresa ir parar nos commits dos meus repositórios open source.

Jogar ~/.claude direto em um repositório git também não resolve: lá dentro ficam o estado de login, o histórico de sessões e as permissões da máquina, e as coisas de cada equipe não podem ir para um repositório público. Por isso escrevi o cclayer, justamente para resolver esse problema.

O que é o cclayer

O cclayer divide a configuração do Claude Code em dois tipos de “camadas”:

• Camada base: o que é igual em todos os computadores: CLAUDE.md, rules/, skills/, output-styles/, agents/, scripts de hook, as chaves compartilhadas do settings.json, a lista de plugins e marketplaces e as definições de MCP. Não tem nenhuma informação de identidade, então pode ficar em um repositório público.
• Camada de sobreposição: uma por equipe. Guarda a identidade git da equipe, os hooks, as regras de endereço de repositório (por exemplo github.com/acme-inc/*) e os arquivos .claude/settings.local.json e CLAUDE.local.md que devem ser escritos nesses projetos. A camada de sobreposição só vale nos projetos correspondentes e não escreve nada em ~/.claude.

Cada computador baixa só a camada base e as sobreposições de que precisa. cclayer apply coloca tudo no lugar com um comando, e cclayer push manda as mudanças locais de volta com outro.

Uma camada pode ser um repositório git ou simplesmente um diretório dentro de uma pasta sincronizada na nuvem, então dá para usar mesmo sem mexer com git.

Instalação

No macOS, com Homebrew:

1
brew install --cask zhaojiannet/tap/cclayer

Para atualizar depois:

1
brew upgrade --cask cclayer

No Linux e no Windows, baixe o binário na página de Releases. É preciso ter o git instalado; as etapas de plugins e MCP exigem o Claude Code 2.1.288 ou superior.

O caso mais simples: uma pessoa, vários computadores

Se não há equipes para separar, uma camada base basta.

O primeiro computador

1
cclayer setup

O setup é uma interface de configuração em tela cheia. A coluna da esquerda mostra as camadas e as configurações da máquina, e a da direita mostra a descrição do item selecionado e os campos editáveis. Nenhum arquivo é gravado antes de você salvar. A interface está disponível em chinês simplificado, inglês e japonês, e por padrão segue o idioma do sistema.

Só é preciso preencher dois campos:

1. Camada base: um diretório (por exemplo ~/Dropbox/cclayer/base na nuvem) ou o endereço de um repositório git privado. Se o diretório ainda não existir, um layer.toml inicial é gerado automaticamente ao salvar.
2. Diretório de projetos: onde fica o seu código, por exemplo ~/Projects.

Escolha “Save and apply” e depois coloque na camada a configuração que este computador já tem:

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

Os caminhos são relativos a ~/.claude. Cada arquivo é verificado antes de entrar: chaves, endereços de e-mail ou caminhos absolutos que apontam para a pasta pessoal da máquina são barrados, e a ferramenta diz em qual linha estão. Se a camada é só sua e fica em um lugar privado, adicione a linha private = true embaixo de [layer] no layer.toml, e os e-mails deixam de ser barrados.

Os outros computadores

Instale o cclayer, rode também cclayer setup, coloque o mesmo endereço na camada base, salve e aplique, e a configuração do primeiro computador chega. Arquivos que já existem na máquina com conteúdo diferente aparecem em uma lista, e ele pergunta se você quer sobrescrevê-los. Antes de sobrescrever, os arquivos antigos são copiados para ~/.local/state/cclayer/backups/.

Sincronização no dia a dia

Se a camada for um repositório git:

1
cclayer push          # Enviar: coleta as mudanças locais, lista o que vai ser commitado e, depois de confirmar, faz commit e push
2
cclayer apply --pull  # Baixar: puxa as camadas mais recentes e aplica na máquina

Se a camada for um diretório na nuvem, quem sincroniza é o serviço de armazenamento. Depois de mudar algo, rode cclayer capture, e no outro computador rode cclayer apply.

Também dá para colocar o hook SessionStart abaixo no claude/settings.json da camada base e ativar “Auto pull” no setup. Assim, toda vez que você abrir uma sessão do Claude Code, tudo é puxado e aplicado automaticamente:

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
}

Uma identidade git diferente para cada equipe

Esse é o principal motivo de eu ter escrito o cclayer. Primeiro crie um repositório privado para a equipe e coloque na raiz um layer.toml com a identidade e os repositórios correspondentes:

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

Depois, nos computadores que precisarem, adicione essa camada de sobreposição. Ele pergunta como configurar as credenciais de acesso ao repositório, faz o clone e verifica tudo:

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

Depois do apply, o cclayer adiciona um bloco include no final do ~/.gitconfig e, usando o includeIf "hasconfig:remote.*.url:..." do git, faz essa identidade valer só nos repositórios cujo endereço remoto corresponde a github.com/acme-inc/*. O conteúdo que já existia no ~/.gitconfig não é alterado. Se a identidade padrão (default_identity) ficar vazia, o git se recusa a commitar em repositórios que não correspondem a nenhuma sobreposição, e acaba aquela história de commitar com o e-mail errado.

As regras de correspondência precisam dizer explicitamente o host e a organização, sem trocá-los por curingas, para que a sobreposição de uma equipe não tome para si os repositórios de outra.

Se você também quiser separar totalmente o login, as sessões e o histórico de prompts do Claude Code de cada equipe, pode ativar o modo profiles. Cada camada de sobreposição ganha seu próprio diretório de configuração ~/.claude-profiles/<nome da camada>, o cclayer env mostra o CLAUDE_CONFIG_DIR correspondente e, junto com o direnv, cada projeto usa automaticamente a configuração certa.

Segurança

Os hooks e skills sincronizados são executados localmente pelo Claude Code, então o cclayer é bem cuidadoso nessa parte:

• Configurações que executam programas ou ativam plugins, como hooks, statusLine e enabledPlugins, além dos arquivos em hooks/ e skills/ e dos arquivos com permissão de execução, são mostradas antes de serem gravadas para você confirmar. Um conteúdo já confirmado não é perguntado de novo.
• Dos trechos de configuração do git, só passam configurações comuns como pull.rebase e push.default. Chaves que podem executar programas, como alias, core.hooksPath e credential.helper, só funcionam se você marcar explicitamente essa camada como confiável na lista de dispositivos.
• O estado de login do Claude Code, o history.jsonl e o projects/ nunca são lidos para dentro de uma camada, e permissions.allow e env ficam na máquina.
• Links simbólicos não são permitidos nas camadas, e ao gravar arquivos eles também não são seguidos.

Comandos mais usados

Para um uso mais detalhado, incluindo como criar os repositórios git, as credenciais de repositórios privados e as perguntas frequentes, veja o tutorial do cclayer (em inglês).

Projeto no GitHub: https://github.com/zhaojiannet/cclayer