Quando o Claude Code trabalha, ele lê muita coisa que você nunca vê: resultado de comando, log de erro, JSON de ferramenta, arquivos inteiros. Tudo isso entra no contexto, que é o espaço de memória de curto prazo do modelo, e quanto mais cheio, mais tokens você gasta e menos cabe para o que importa.
O Headroom é um projeto de código aberto (licença Apache 2.0) que espreme esse material antes de ele chegar ao modelo. Segundo o README, a compressão roda na sua máquina e nenhum conteúdo de prompt ou de arquivo é enviado a lugar nenhum para ser comprimido.
Este guia traz o que o vídeo cortou: o comando de instalação, o passo a passo do wrap, como desfazer, como medir a economia no seu próprio uso e o que o learn faz com o seu CLAUDE.md. Os dados vêm do README do projeto, conferido em 22/10/2026. O projeto é novo e muda rápido, então um comando pode estar diferente na versão que você instalar.
Comando de instalação
A CLI do Headroom vem do pacote Python headroom-ai, no PyPI. Isso quer dizer que você precisa do Python instalado (o README pede Python 3.10 ou mais novo). Há duas formas de instalar:
# CLI em um ambiente isolado (recomendado pelo README)
uv tool install --python 3.13 "headroom-ai[all]"
# ou, com o pip
pip install "headroom-ai[all]"
O pacote headroom-ai do npm é só a biblioteca para TypeScript e não traz o comando headroom. Para usar com o Claude Code, instale o do Python.
Depois de instalar, rode o teste de saúde:
headroom doctor
O headroom doctor confirma que o roteamento está funcionando. Se ele reclamar de algo, resolva antes de seguir.
Passo a passo do wrap
O wrap é o jeito mais curto de ligar tudo. Em vez de abrir o Claude Code como sempre, você abre assim, dentro da pasta do seu projeto:
headroom wrap claude
O que acontece, segundo o README: o Headroom sobe um proxy local (um intermediário na sua máquina), instala o Serena para navegação semântica de código e abre o Claude Code já configurado para passar pelo Headroom. No Claude Code, o Serena é registrado só para o projeto onde você está. Sua autenticação e o modelo escolhido continuam os mesmos.
Você precisa abrir a sessão assim toda vez que quiser a compressão. Abrir o Claude Code pelo comando normal não passa pelo Headroom.
Como desfazer
headroom unwrap claude
O headroom unwrap remove a configuração e o registro do Serena. Se você só quer parar de usar, basta voltar a abrir o Claude Code pelo comando de sempre.
Como usar o headroom learn
O headroom learn lê as sessões em que algo deu errado e escreve as correções em arquivos de instrução. Por padrão ele grava em CLAUDE.local.md, que fica fora do Git. Também pode gravar em CLAUDE.md, AGENTS.md, GEMINI.md ou GROK.md.
Na prática, é o Claude Code deixando de repetir o mesmo erro: o que falhou numa sessão vira instrução para a próxima. Como ele mexe em arquivo que o agente lê, olhe o que foi escrito antes de confiar. O README descreve também uma variante com --verbosity, que tem modo de ensaio (mostra o que achou, sem aplicar) e o --apply para salvar. Rode o ensaio primeiro.
Como medir a economia com headroom savings
Não confie em número de vitrine, meça o seu:
headroom savings
O README manda rodar o headroom savings contra o seu próprio tráfego, porque a economia depende do que o agente lê. O headroom dashboard mostra o ganho ao vivo, com o proxy rodando.
O limite honesto
- O vídeo mostra 55.957 tokens caindo para 24.340 (57%) num cenário de depuração de incidente. É um teste do próprio projeto, com saída de ferramenta repetitiva.
- Na mesma tabela do README os outros cenários economizam menos: 21% numa busca de código, 42% na exploração de código e 30% na triagem de problemas.
- Texto corrido e saída que já é enxuta quase não encolhem. O próprio README diz isso.
- O README fala em tokens, não em limite do plano de assinatura do Claude. Este guia não promete que você vai poder usar mais no plano.
Fontes
- README do Headroom: https://github.com/headroomlabs-ai/headroom (acessado em 22/10/2026)
- Documentação: https://docs.headroomlabs.ai/docs (indicada no README)