🇧🇷 Português  |  🇺🇸 English

.code Powershell Backup

Backup e restore completo do Claude Code para Windows via PowerShell 7+.

Um único script (code-ps-backup.ps1) gerencia init, backup e restore através do parâmetro -Action.

---

Requisitos

• PowerShell 7.0 ou superior (pwsh)
• Git (disponível no PATH)
• Claude Code instalado e executado ao menos uma vez

---

Início rápido

# 1. Inicializar o repositório de backup
pwsh code-ps-backup.ps1 init

# 2. Executar o primeiro backup
pwsh code-ps-backup.ps1 backup

# 3. Restaurar em uma nova máquina
pwsh code-ps-backup.ps1 restore -DryRun   # ver o que será restaurado
pwsh code-ps-backup.ps1 restore            # restaurar interativamente

---

Ações

init

Configura o repositório de backup pela primeira vez.

• Verifica se o Claude Code está instalado
• Detecta se o OpenCode (~/.config/opencode/) e o diretório ~/.agents/ existem
• Inicializa um repositório Git no diretório de backup
• Cria um .gitignore mínimo
• Lista os projetos encontrados em ~/.claude/projects/ e permite selecionar quais incluir
• Gera o arquivo backup-config.json

pwsh code-ps-backup.ps1 init
pwsh code-ps-backup.ps1 init -BackupDir C:\MeuBackup

---

backup

Copia os arquivos alterados de ~/.claude/ para o repositório de backup, faz commit Git e opcionalmente envia para o remote.

O que é incluído:

Categoria	Origem	Destino no backup
Configurações globais	~/.claude/*.md, settings.json, settings.local.json, keybindings.json	global/
MCP config	~/.claude.json	global/claude.json
Skills	~/.claude/skills/	skills/
Plugins	~/.claude/plugins/	plugins/
Plans	~/.claude/plans/	plans/
Commands	~/.claude/commands/	commands/
Agents	~/.claude/agents/	agents/
Output styles	~/.claude/output-styles/	output-styles/
Rules	~/.claude/rules/	rules/
Hooks	~/.claude/hooks/	hooks/
Scheduled tasks	~/.claude/scheduled-tasks/	scheduled-tasks/
Todos	~/.claude/todos/	todos/
OpenCode config	~/.config/opencode/	opencode/
Agents home	~/.agents/	agents-home/
Codex CLI	%USERPROFILE%\.codex\	codex/
Path customizado	qualquer diretório via -CustomPath	custom/<nome>/
Projetos	~/.claude/projects/<nome>/	projects/<nome>/

Por projeto são incluídos: memory/, sessões (.jsonl, .meta.json), subagents/ e tool-results/.

Nota sobre sessões: no backup as sessões ficam em projects/<nome>/sessions/; no restore são copiadas de volta para a raiz do projeto em ~/.claude/projects/<nome>/, que é onde o Claude Code as espera.

O sync é bidirecional: arquivos removidos na origem também são removidos no backup.

pwsh code-ps-backup.ps1 backup
pwsh code-ps-backup.ps1 backup -BackupDir C:\MeuBackup
pwsh code-ps-backup.ps1 backup -SanitizeDir C:\ExportPublico
pwsh code-ps-backup.ps1 backup -CustomPath C:\MinhaConfig

O flag -SanitizeDir gera uma cópia sanitizada — sem tokens, senhas, caminhos absolutos ou dados de sessão — adequada para compartilhar publicamente.

---

restore

Copia os arquivos do repositório de backup de volta para ~/.claude/, ~/.config/opencode/, e ~/.agents/. Antes de sobrescrever qualquer arquivo existente, cria um .backup.<timestamp> automaticamente.

O restore detecta automaticamente se o backup foi feito com um nome de usuário diferente e oferece remapear os caminhos de projetos para o usuário atual.

# Ver o que seria restaurado sem alterar nada
pwsh code-ps-backup.ps1 restore -DryRun

# Modo interativo: pergunta categoria por categoria
pwsh code-ps-backup.ps1 restore

# Não-interativo: restaura tudo sem perguntar (remap de usuário é auto-detectado)
pwsh code-ps-backup.ps1 restore -Yes

# Especificar manualmente o usuário antigo (caso a auto-detecção falhe)
pwsh code-ps-backup.ps1 restore -Yes -RemapUserFrom rapha

# Combinações com diretório customizado
pwsh code-ps-backup.ps1 restore -BackupDir C:\MeuBackup -DryRun
pwsh code-ps-backup.ps1 restore -BackupDir C:\MeuBackup -Yes

No modo -DryRun, cada arquivo é classificado como NEW, CHANGED ou SAME. Nenhum arquivo é escrito.

---

Parâmetros

Parâmetro	Valores	Descrição
-Action	init, backup, restore	(Obrigatório) Operação a executar
-BackupDir	caminho	Diretório do repositório de backup. Padrão: diretório pai do script
-SanitizeDir	caminho	(backup only) Diretório de saída para exportação sanitizada
-Yes	switch	(restore only) Pula todos os prompts interativos
-DryRun	switch	(restore only) Apenas analisa, não escreve nada
-RemapUserFrom	string	(restore only) Sobrescreve o usuário detectado automaticamente para remap de projetos
-CustomPath	caminho	(backup only) Inclui um diretório adicional no backup (um por execução)

---

Arquivo de configuração

O init gera backup-config.json no diretório de backup. Edite manualmente conforme necessário.

{
  "version": 1,
  "claude_dir": "~/.claude",
  "include_sessions": true,
  "include_todos": true,
  "projects": [
    "C--Users-usuario-projetos-meu-app"
  ],
  "git_auto_push": false,
  "git_remote": "origin",
  "git_branch": "main",
  "opencode_dir": "~/.config/opencode",
  "include_opencode": true,
  "agents_home_dir": "~/.agents",
  "include_agents_home": true,
  "mirror_dir": "",
  "backup_codex": true,
  "backup_custom": true
}

Campo	Tipo	Descrição
version	int	Versão do schema (sempre 1)
claude_dir	string	Caminho para o diretório do Claude. ~ é expandido
include_sessions	bool	Incluir arquivos de sessão (.jsonl, .meta.json)
include_todos	bool	Incluir todos de ~/.claude/todos/
projects	array	Nomes das pastas em ~/.claude/projects/ para incluir
git_auto_push	bool	Enviar automaticamente após cada backup com sucesso
git_remote	string	Nome do remote Git (padrão: origin)
git_branch	string	Branch alvo do push (padrão: main)
opencode_dir	string	Caminho para o diretório global do OpenCode
include_opencode	bool	Incluir config do OpenCode no backup
agents_home_dir	string	Caminho para ~/.agents (skills globais de agentes)
include_agents_home	bool	Incluir ~/.agents no backup
mirror_dir	string	Pasta espelho sincronizada por serviço (ex: OneDrive). Vazio = desativado
backup_codex	bool	Incluir %USERPROFILE%\.codex\ no backup (padrão: true)
backup_custom	bool	Habilitar backup de path customizado via -CustomPath (padrão: true)

---

Exportação sanitizada (-SanitizeDir)

Gera uma cópia do backup sem dados sensíveis, adequada para um repositório público ou para compartilhar configurações.

O que é removido / substituído:

• Valores de variáveis de ambiente (env) em servidores MCP no claude.json → <REDACTED>
• Metadados por projeto (lastCost, tokens, IDs de sessão, etc.) são omitidos; apenas mcpServers e allowedTools são mantidos
• Comandos de servidores MCP com caminho absoluto → <PATH>
• Argumentos de servidores MCP: caminhos absolutos → <PATH>, hosts/IPs → <HOSTNAME>, URLs → <URL>, tokens de autorização → <AUTH_TOKEN>
• Permissões de ferramentas MCP em settings.json → mcp__<server>__<tool>
• Arquivos de sessão (.jsonl, .meta.json) são sempre excluídos
• Memory de projetos: pergunta interativamente qual incluir

O que é preservado: skills, plugins, agents, commands, plans, rules, hooks, keybindings, arquivos Markdown globais e codex/ (com caminhos substituídos por <PATH>).

Comportamento das novas categorias no export sanitizado:

• codex/ é incluído com caminhos absolutos, IPs e hostnames substituídos
• custom/ é excluído por padrão (pode conter qualquer tipo de dado)

---

Backup automático (Task Scheduler)

Para agendar backups diários sem janela:

1. Abra o Agendador de Tarefas (taskschd.msc)
2. Crie uma nova tarefa básica com:
   • Programa: pwsh.exe
   • Argumentos: -NonInteractive -WindowStyle Hidden -File "C:\caminho\code-ps-backup.ps1" backup "C:\MeuBackup"
3. Ative "git_auto_push": true no backup-config.json para sincronizar automaticamente

---

Estrutura do repositório de backup

<BackupDir>/
  backup-config.json
  .gitignore
  global/
    *.md                 # todos os *.md de ~/.claude/ (ex: CLAUDE.md)
    settings.json
    settings.local.json
    keybindings.json
    claude.json          # MCP config (~/.claude.json)
  skills/
  plugins/
  agents/                # ~/.claude/agents/
  commands/
  plans/
  rules/
  hooks/
  output-styles/
  scheduled-tasks/
  todos/
  opencode/              # ~/.config/opencode/
  agents-home/           # ~/.agents/
  codex/                 # %USERPROFILE%\.codex\
  custom/
    <nome>/              # conteúdo do -CustomPath
    <nome>.origin.json   # caminho original (usado no restore)
  projects/
    <nome-do-projeto>/
      memory/
      sessions/          # restaurado para a raiz do projeto no restore
      subagents/
      tool-results/

---

Migrar para uma nova máquina

# Na nova máquina, clone o repositório de backup
git clone git@github.com:seu-usuario/code-ps-backup.git C:\MeuBackup

# Restaure tudo (o script detecta automaticamente se o usuário mudou e oferece remap)
pwsh C:\caminho\code-ps-backup.ps1 restore -BackupDir C:\MeuBackup -Yes

# Se o usuário da nova máquina for diferente e a auto-detecção falhar:
pwsh C:\caminho\code-ps-backup.ps1 restore -BackupDir C:\MeuBackup -Yes -RemapUserFrom usuario-antigo

O restore cria automaticamente um .backup.<timestamp> de qualquer arquivo existente antes de sobrescrever.

Remap de usuário de projetos

Os projetos do Claude ficam em pastas com o nome do caminho codificado, ex: C--Users-rapha-MeuProjeto. Ao restaurar com um usuário diferente (ex: john), o script detecta automaticamente o usuário antigo nas pastas do backup e pergunta se deve remapear para o usuário atual, resultando em C--Users-john-MeuProjeto.

---

Mirror para OneDrive / cloud

Configure mirror_dir no backup-config.json para que, após cada backup, o conteúdo seja copiado (via robocopy) para uma pasta sincronizada pelo OneDrive (ou qualquer outro serviço):

"mirror_dir": "C:\\Users\\seu-usuario\\OneDrive\\Backups\\claude-settings"

A pasta espelho recebe todos os arquivos do backup, exceto o histórico Git (.git/), para que o OneDrive sincronize apenas o estado atual sem conflitos de lock de arquivos Git.