config-gc

Config GC — Coleta de Lixo para Configurações do Claude Code

Emprestado da coleta de lixo de tempo de execução: varrer periodicamente em busca de objetos que não são mais referenciados, redundantes, expirados ou de baixo valor, e recuperar o espaço. A diferença crítica: aqui, a coleta requer um humano no loop. Nunca exclua autonomamente.

Quando Ativar

• O usuário pede para limpar, auditar ou reduzir sua configuração do Claude Code
• O usuário reclama sobre muitos skills, hooks barulhentos ou inicialização lenta da sessão
• Uma revisão mensal/periódica da configuração está prevista
• Após instalar um pacote grande de skills (por exemplo, este repositório), para reconciliar sobreposições com a configuração existente

NÃO ativar para: limpar código-fonte do projeto (isso é refatoração), limpar histórico de chat ou desinstalar o próprio Claude Code.

Filosofia de Design

1. Configurações somente de adição vazam. Skills, arquivos de memória, hooks e entradas de permissão só são adicionados. Sem revisão periódica, eles apodrecem silenciosamente.
2. Auditorias regulares superam purgas únicas. Varredura a cada ~30 dias, proponha um pequeno lote de candidatos a cada vez.
3. Estratégias por canal. Cada tipo de acúmulo (skills, hooks, permissões, ...) tem seus próprios sinais de obsolescência — não aplique uma regra em todos os lugares.
4. Soft-delete primeiro. Renomear para .disabled > mover para ~/.claude/_gc_trash/ > exclusão real. Sempre mantenha um caminho de desfazer.
5. Humano no loop forçado. Cada candidato recebe sua própria confirmação [y/n/skip]. Nenhum atalho "sim para todos".
6. Mantenha um log. Cada execução de GC anexa a ~/.claude/gc_log.md: o que foi tocado, por que e como desfazer.

Canais de Varredura

#	Canal	Caminho	Sinais de obsolescência / redundância
1	Skills	~/.claude/skills/*/	Nomes com forte sobreposição; nunca acionados em transcrições recentes; incompatibilidade de domínio com o trabalho real do usuário; SKILL.md quebrado ou vazio
2	Memória	~/.claude/**/memory/*.md + seu índice	Múltiplas entradas de índice para um tópico; conteúdo contradizendo entradas mais recentes; datas que já passaram; arquivos órfãos ausentes do índice; fragmentos com menos de 100 palavras que deveriam ser mesclados
3	Hooks	~/.claude/hooks/ + configurações	Scripts presentes no disco, mas não referenciados por nenhuma configuração de hook; versões antigas substituídas por reescritas
4	Permissões	permissions.allow em settings.json / settings.local.json	Entradas duplicadas; entradas específicas já cobertas por um curinga (por exemplo, Bash(git push) quando Bash(*) é permitido); concessões pontuais de experimentos passados
5	Servidores MCP	~/.claude.json ou .mcp.json do projeto	Servidores que falham ao conectar; duplicatas funcionais; há muito não usados
6	Lembretes / tarefas agendados	onde quer que o usuário os mantenha	Disparos únicos com mais de 30 dias; tarefas cujos scripts de destino não existem mais
7	Histórico do projeto	~/.claude/projects/*/	Snapshots de handoff desatualizados; registros de sessão substituídos por estado mais recente
8	Caches de runtime	cache/, file-history/, logs/, shell-snapshots/	Classificar por tamanho e mtime; propor itens com mais de 30 dias e grandes

Fluxo de Trabalho

1. Varrer todos os canais (ou o subconjunto que o usuário nomear). Coletar candidatos com: caminho, canal, sinal que o sinalizou, tamanho, última modificação.
2. Classificar por confiança (quebrado/órfão = alto; apenas antigo = baixo) e apresentar como uma tabela numerada. Limitar cada execução a ~20 candidatos — GC é periódico, não exaustivo.
3. Confirmar um por um. Para cada candidato, mostrar a evidência, depois perguntar [y/n/skip]. O usuário pode parar a qualquer momento.
4. Soft-delete itens confirmados: preferir renomear para .disabled para skills/hooks e mover para _gc_trash/<data>/ para arquivos. Entradas de permissão vivem em JSON (sem comentários possíveis): fazer backup do arquivo de configurações, registrar cada entrada removida textualmente em gc_log.md, depois removê-la do array allow com jq. Excluir permanentemente apenas quando o usuário solicitar explicitamente.
5. Registrar a execução em ~/.claude/gc_log.md: timestamp, itens processados, instruções de desfazer.
6. Relatar: tamanho recuperado, canais ainda saudáveis, data sugerida para próxima revisão.

Exemplos de Comandos de Varredura

Scripts de hook órfãos (canal 3) — scripts no disco que nenhuma configuração de hook referencia:

for f in ~/.claude/hooks/*; do
  name=$(basename "$f")
  grep -rq "$name" ~/.claude/settings.json ~/.claude/settings.local.json 2>/dev/null \
    || echo "ÓRFÃO: $f"
done

Entradas de permissão redundantes (canal 4) — duplicatas e concessões específicas ofuscadas por um curinga:

jq -r '.permissions.allow[]' ~/.claude/settings.local.json | sort | uniq -d
if jq -e '.permissions.allow | index("Bash(*)")' ~/.claude/settings.local.json >/dev/null; then
  jq -r '.permissions.allow[]' ~/.claude/settings.local.json \
    | grep '^Bash(' | grep -vF 'Bash(*)'
fi

Maiores caches obsoletos (canal 8) — du -k em vez de find -printf (apenas GNU), para funcionar também no macOS/BSD:

find ~/.claude/file-history ~/.claude/shell-snapshots -type f -mtime +30 \
  -exec du -k {} + 2>/dev/null | sort -rn | head -20

Soft-delete com caminho de desfazer (capturar a data uma vez para que o log não possa discordar do diretório):

gc_date=$(date +%Y-%m-%d)
mkdir -p ~/.claude/_gc_trash/$gc_date
mv ~/.claude/skills/dead-skill ~/.claude/_gc_trash/$gc_date/
echo "$(date -Iseconds) moveu skills/dead-skill -> _gc_trash/$gc_date/ (desfazer: mv de volta)" >> ~/.claude/gc_log.md

Removendo uma entrada de permissão confirmada como redundante (JSON não tem comentários — fazer backup, registrar, depois editar):

cp ~/.claude/settings.local.json ~/.claude/settings.local.json.bak
echo "$(date -Iseconds) removeu entrada de permissão: Bash(git push) (desfazer: restaurar de .bak ou readicionar)" >> ~/.claude/gc_log.md
jq '.permissions.allow -= ["Bash(git push)"]' ~/.claude/settings.local.json.bak \
  > ~/.claude/settings.local.json

Antipadrões

• Aprovação em massa. Perguntar "excluir todos os 15? [y/n]" derrota o design. Um item, uma decisão.
• Exclusão definitiva na primeira passagem. Se não houver uma cópia em _gc_trash/ ou renomeação para .disabled, você fez errado.
• Tratar "antigo" como "morto". Um skill não tocado por 60 dias pode ser sazonal (temporada de impostos, revisões trimestrais). Idade é um sinal, não um veredito — é por isso que um humano confirma.
• Limpar memória por truncamento. Mesclar dois arquivos de memória contraditórios requer ler ambos e manter a verdade mais recente, não excluir o mais longo.
• Tocar qualquer coisa fora de ~/.claude (ou do .claude/ do projeto). O GC de configuração nunca vagueia por árvores de código-fonte.

Melhores Práticas

• Execute após grandes adições, não apenas em um calendário: instalar um pacote de 50 skills é exatamente quando a sobreposição com skills existentes aparece.
• Quando dois skills se sobrepõem, prefira desabilitar aquele com a descrição de gatilho mais fraca — é o que provavelmente nunca estava sendo acionado de qualquer maneira.
• A limpeza de permissões é o canal de maior valor por minuto gasto: entradas allow redundantes dificultam a revisão de segurança.
• Mantenha gc_log.md para sempre. É pequeno, e "quando desabilitei aquele hook e por quê" surge com mais frequência do que você imagina.

Skills Relacionados

• skill-stocktake — audita a qualidade do skill; o config-gc audita a existência do skill. Execute stocktake no que sobreviver ao GC.
• workspace-surface-audit — a contraparte aditiva: recomenda o que instalar. O config-gc é a metade subtrativa do mesmo ciclo de vida.
• configure-ecc — depois de instalar skills com ele, execute config-gc para reconciliar sobreposições com sua configuração pré-existente.
• continuous-learning — produz os arquivos de memória que este skill audita posteriormente.
• security-review — funciona bem em conjunto com o canal de permissões.