Como comprimir o CLAUDE.md com o caveman compress sem perder o arquivo original?

Fala aí, beleza? Aquele CLAUDE.md que começou com cinco linhas hoje tem regra de commit, padrão de pasta, lista de comandos e três avisos em CAIXA ALTA que você mesmo esqueceu por que escreveu

Arquivo de memória não é documentação parada num canto: ele é lido a cada conversa nova

Ou seja, cada linha inchada não custa uma vez, ela custa em TODA sessão, sempre como token de entrada

É aí que entra o caveman compress, o skill que encolhe o arquivo de memória em Markdown e guarda uma cópia legível do texto antigo, pra você poder voltar atrás

Até o fim do post tu vai saber instalar o plugin, rodar o comando no arquivo certo, entender o que acontece por baixo e o que fazer quando a compressão não passa na validação 🙂

O que você precisa antes de comprimir o arquivo de memória

A lista é curtinha:

• Claude Code instalado e funcionando, com a CLI de plugins disponível
• O arquivo de memória em Markdown que você quer encolher (o clássico CLAUDE.md)
• Um repositório versionado ou uma cópia sua do arquivo, como rede de segurança extra

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Se o seu Claude Code nem autentica direito ainda, resolve isso primeiro, porque plugin nenhum salva sessão que morre no login: a gente já destrinchou o assunto no post sobre erro de autenticação da chave API

Atenção no tipo de arquivo, isso é importante! O compress só atua em linguagem natural

Permitidos: .md, .txt, .typ, .typst, .tex e arquivos sem extensão

Nunca modificados: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css, .html, .xml, .sql, .sh

E se o arquivo for misto, prosa com trecho de código no meio, ele comprime só a prosa

O projeto é criado e mantido por Julius Brussee, no repositório JuliusBrussee/caveman, que é onde mora a documentação do skill

Passo a passo: como comprimir o CLAUDE.md com o Caveman

Bora ver na prática?

1. Adicione o marketplace e instale o plugin pela CLI do Claude Code

claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

O erro comum aqui é pular o marketplace add e ir direto no plugin install: sem registrar a origem, o Claude Code não sabe de onde tirar o caveman@caveman

2. Se preferir, use o caminho alternativo via npm

npm install -g @caveman-ai/cli && caveman setup --install caveman claude

Esse instalador configura o Claude Code pra você

O erro comum deste passo é achar que precisa dos dois caminhos: é um OU outro, não os dois somados

3. Rode o comando namespaced passando o caminho do arquivo

/caveman:compress CLAUDE.md

O erro comum é chamar o comando sem o caminho do arquivo, ou esquecer o namespace do plugin (caveman:) na frente do compress

O argumento é o caminho, então vale apontar pra qualquer arquivo de texto permitido, não só o CLAUDE.md da raiz

4. Entenda o que roda por dentro antes de sair rodando em tudo

O pipeline é econômico de propósito: a detecção do tipo de arquivo é local (não gasta token), a compressão em si é UMA chamada ao modelo, e a validação volta a ser local

Essa validação checa títulos, blocos de código, URLs, caminhos de arquivo e bullets

Se algo quebrou, aí sim o modelo é acionado de novo, só pra consertar os trechos quebrados, sem recomprimir o arquivo inteiro, em até 2 tentativas

Ou seja, no caminho feliz é chamada única, e a correção só entra em cena quando a validação reprova

5. Confira o resultado e ache o backup

A versão comprimida substitui o arquivo (o seu CLAUDE.md continua sendo o CLAUDE.md)

O backup humano legível fica como <arquivo>.original.md, gravado FORA da árvore do projeto, em diretório de dados do sistema:

macOS e Linux: $XDG_DATA_HOME/caveman-compress/backups/<nome-da-pasta-pai>/
Windows:       %LOCALAPPDATA%\caveman-compress\backups\<nome-da-pasta-pai>\

O erro comum é procurar o backup dentro do projeto e achar que ele sumiu

Ele mora fora de propósito, pra carregador de skill não reler o backup como se fosse arquivo vivo (senão você pagaria pelo texto duas vezes, o comprimido e o original haha)

Deu errado? Como recuperar o CLAUDE.md original

Sintoma: a compressão falhou na validação:

Causa: o texto gerado não passou nos checks locais de título, bloco de código, URL, caminho ou bullet

Solução: nada a fazer, o arquivo original NÃO é alterado quando a compressão falha

Parece frustrante, mas é o comportamento que você quer: falhou, ficou tudo como estava

Sintoma: quero voltar ao texto antigo ou editar o que foi cortado:

Causa: a versão comprimida é enxuta demais pro seu gosto, ou cortou uma instrução que você fazia questão de manter no detalhe

Solução: abra o <arquivo>.original.md no diretório de dados do sistema

Ele é legível por humano, dá pra ler, editar e rodar o skill de novo em cima do texto ajustado

Sintoma: meu arquivo é misto, tem prosa e código junto:

Causa: medo justo de ver o snippet de exemplo virar papinha

Solução: em arquivo misto o compress comprime só a prosa, e as extensões da lista bloqueada ele nunca modifica

Como prevenir dor de cabeça: mantenha o arquivo versionado, saiba onde o backup mora no SEU sistema operacional e lembre que a v1.10.0 passou a usar UTF-8 explícito e escrita atômica

Na prática isso quer dizer que uma queda no meio da escrita não trunca mais o arquivo, inclusive no Windows

Quando vale a pena comprimir o arquivo de memória (e quando não)

Os cenários em que a conta fecha bonito:

• CLAUDE.md de projeto que virou manual, com dezenas de regras acumuladas
• Memória global que você foi engordando por meses e nunca releu
• Monorepo com vários arquivos de memória sendo carregados juntos na mesma sessão

E os casos em que não compensa: arquivo pequeno (não tem gordura pra tirar) ou arquivo que você edita na mão toda semana e prefere ler o texto original no lugar, sem ter que abrir o backup

Vale separar duas coisas que dividem o mesmo nome e confundem geral: o compress e o skill de resposta caveman são bichos diferentes

O compress mexe no que ENTRA (o arquivo de memória), o skill de resposta mexe no ESTILO da saída do modelo

Outro ponto: o arquivo de memória vai inteiro pro modelo em toda sessão, então vale a mesma pergunta que a gente já levantou sobre privacidade das suas fontes, ou seja, saber o que você está mandando e por quanto tempo

E se você rodar mais de um agente, o Caveman é distribuído também como plugin do Codex, extensão do Gemini CLI e arquivos de regra pra Cursor, Windsurf, Cline e Copilot via npx skills

Quanto isso economiza de verdade em tokens?

Aqui é onde a maioria dos posts sai jogando número, então vamos com a origem de cada um na mesa

Os 46% são do compress, o assunto deste post, e vêm do benchmark do próprio projeto

Os 65% são de OUTRA coisa: o skill de resposta, medido em benchmark de prosa de chat com 10 prompts

A v1.10.0 adotou 65% como número único e aposentou tanto a faixa de 50% a 65% quanto a alegação de 75%, o que já diz bastante sobre o cuidado do projeto com o próprio marketing

O contraponto independente é da JetBrains: teste A/B pareado conduzido por Denis Shiryaev, com Harbor 0.17 e Claude Sonnet 5 em esforço de raciocínio baixo, em 86 tarefas do SkillsBench

Resultado: 8,5% de economia de tokens de saída, com a qualidade se mantendo

Distância grande do número de laboratório, né? Tarefa real de coding agent não é prosa de chat

Tem ainda o custo fixo do skill de resposta: cerca de 1.000 a 1.500 tokens de entrada POR TURNO

O /caveman-stats passou a subtrair esse custo e mostrar como negativas as cargas de trabalho em que a conta não fecha

E o projeto publicou o docs/HONEST-NUMBERS.md, que orienta desligar o Caveman se ele for negativo pra sua carga

Achei massa isso: ferramenta que te ensina a medir se ela vale a pena é raridade

Veredito: pra arquivo de memória grande, o compress tem a conta mais favorável dos dois, porque o ganho não acontece uma vez, ele se repete em toda sessão que lê aquele arquivo

Conclusão

Arquivo de memória é custo recorrente, e é justamente isso que faz o inchaço doer no bolso sem você perceber

Comprimir com backup te dá o melhor dos dois mundos: o arquivo enxuto no projeto e o texto antigo guardado, caso você queira voltar atrás

O próximo passo é bem simples: instala, roda em uma cópia ou num CLAUDE.md versionado, compara o resultado com o .original.md e decide se mantém

De olho no rumo do projeto também: a linha Caveman 2 vai além do arquivo de memória e comprime saídas de ferramentas, logs, código e JSON antes de chegar ao modelo, com recuperação byte a byte e benchmark fixado no Claude Code reportando 33,2% menos tokens de entrada segundo o provedor

Sobre adoção, o repo acumula ordem de grandeza de 98,7 mil estrelas em 18/08/2026 pelo registro skills.sh, com agregadores divergindo entre aproximadamente 96,6 mil e 99,3 mil, então trate como ordem de grandeza mesmo, não como placar exato

Agora vai lá encolher aquele manual que você chama de arquivo de memória 😀

até o próximo post!