Você troca de máquina, abre o Claude Code, e o ~/.claude/ está vazio. Sem CLAUDE.md, sem hooks, sem skills, sem os agentes e comandos que você escreveu ao longo de meses, sem a memória por projeto que guardava decisões antigas. A tentação óbvia é clonar o repositório de backup e copiar tudo para dentro do diretório novo — e quase funciona. Dois pedaços ficam de fora desse caminho rápido. O índice vetorial de memória é um — nenhum git clone o traz, porque está fora do controle de versão. O arquivo de configuração legado do Claude Code é o outro — hoje não vive em nenhuma camada do backup.
Este é o procedimento documentado no meu próprio repositório de backup, o Project_Setup, escrito depois de um incidente real em que um arquivo binário ficou sem cópia por dias. O que este tutorial traz são os passos que essa documentação prescreve para restaurar o ambiente numa máquina nova, mais o que fazer nos dois pontos em que o caminho rápido, sozinho, não resolve.
O que você precisa
- Acesso ao repositório de backup no GitHub (Project_Setup)
- Acesso à cópia em nuvem mais ampla — a que roda todo dia à noite — necessária se você quiser recuperar o índice vetorial de memória sem reconstruí-lo do zero
- Acesso ao gerenciador de senhas onde os segredos originais estão guardados
- Git instalado
- Python instalado, para o caminho alternativo de reconstrução do índice
- Tempo: minutos para copiar os arquivos; se precisar reconstruir o índice do zero, mais tempo do que isso — não há um número documentado, então este tutorial não estima um
Passo 1: Clone o repositório de backup
Clone o repositório Project_Setup do GitHub para a máquina nova:
git clone <url-do-repositorio-project-setup>
Depois do clone, você tem uma pasta local com CLAUDE.md, settings.json (com os segredos redigidos) e os diretórios hooks/, memory/, skills/, agents/, commands/, projects/. O índice vetorial de memória não vem junto — esse arquivo é ignorado pelo controle de versão, e só reaparece no Passo 4.
Passo 2: Copie o conteúdo para ~/.claude/
A partir da pasta clonada, copie cada peça para dentro de ~/.claude/ na máquina nova:
cp -r CLAUDE.md settings.json hooks memory skills agents commands projects ~/.claude/
Depois do passo, o ~/.claude/ da máquina nova replica a estrutura de diretórios da máquina antiga — CLAUDE.md, settings.json, hooks, memória, skills, agentes, comandos e projetos, todos no lugar. O índice vetorial de memória continua ausente; isso é esperado até o Passo 4.
Passo 3: Recoloque os segredos reais
O settings.json copiado tem cada valor sensível trocado por um marcador neutro de redação. Não existe um inventário documentado de quais chaves precisam voltar — a única forma confiável de achar todas é buscar, dentro do arquivo, cada ocorrência desse marcador:
grep -n "<marcador-de-redacao>" ~/.claude/settings.json
Abra o gerenciador de senhas onde os segredos originais estão guardados e cole o valor real de volta, um por um, em cada linha que a busca apontou. Depois do passo, rodar o mesmo grep de novo não deve retornar nenhuma linha.
Passo 4: Recupere o índice vetorial de memória
Dois caminhos, nessa ordem de preferência. Se você tem acesso à cópia em nuvem mais ampla — a que roda todo dia à noite — copie o arquivo do índice de lá direto para a raiz de ~/.claude/, não para dentro de memory/ nem de qualquer outro subdiretório.
Se não tem acesso a essa cópia, reconstrua o índice do zero. Rode o indexador em modo de reconstrução completa, a partir dos arquivos-fonte em markdown que os dois primeiros passos já restauraram:
python ~/.claude/memory/scripts/<script-indexador>.py --modo reconstrucao-completa
Reconstruir custa tempo e chamadas de API. Quanto — a documentação não registra um número, e este tutorial não vai inventar um. Depois do passo, o arquivo do índice mora na raiz de ~/.claude/, nunca dentro de memory/.
Passo 5: Reinicie o Claude Code
Feche a sessão atual e abra o Claude Code de novo na máquina nova. Depois do passo, você vê os hooks carregando na inicialização, as skills aparecendo na lista disponível, e a memória sendo puxada nas primeiras respostas — sinal de que o índice, copiado ou reconstruído, está sendo lido.
Nenhum desses cinco passos foi testado de ponta a ponta numa máquina real ou simulada. O que foi testado, e é uma coisa diferente, foi o pipeline de alerta de falha do backup — com uma falha sintética injetada só para confirmar que o aviso chega até mim. Isso quer dizer que os passos acima são o que a minha documentação prescreve, não uma restauração validada na prática. Trate este tutorial como uma lista de passos plausível até o dia em que alguém — talvez você — rodar ela inteira contra uma perda de verdade.
O que pode dar errado
- O índice vetorial de memória não vem no
git clone, porque está fora do controle de versão. Se você pular a cópia em nuvem e não tiver acesso a ela, a única saída é reconstruir do zero pelo Passo 4, segundo caminho. - O arquivo de configuração legado do Claude Code — servidores MCP, plugins, permissões, conta vinculada — não está em nenhuma camada do backup hoje, porque vive um nível acima do diretório espelhado. Se ele se perder, a única saída é reconstruir cada configuração de memória, uma por uma, na mão.
- Colar o índice recuperado da nuvem dentro do subdiretório errado —
memory/em vez da raiz de~/.claude/— cria um índice novo e vazio ao lado do restaurado, sem nenhum aviso. Os dois passam a coexistir em silêncio, e você só percebe quando a memória parece incompleta. - Faltam ainda, sem solução documentada: um arquivo de histórico de comandos e um diretório de planos, nenhum dos dois coberto por qualquer camada do backup.
Próximos passos
Depois de restaurar, compare manualmente o que existe em ~/.claude/ contra o manifesto do backup — não existe automação para essa comparação ainda, e é o item óbvio no topo da lista.
Vale considerar incluir o arquivo de configuração legado numa camada de backup futura; hoje ele simplesmente não está coberto, e é a lacuna mais cara das duas listadas acima.
Um procedimento de restauração só é confiável no dia em que alguém o executa de ponta a ponta antes de precisar dele de verdade. Até esse dia, o que existe aqui é uma lista de passos plausível — não uma garantia testada.
