Seu agente paga em tokens por tudo que lê. Logs repetidos, JSON gigante e arquivos relidos ocupam espaço mesmo quando a resposta está numa linha. Headroom comprime esse material no seu computador antes de enviá-lo ao modelo. Os originais ficam em cache local e o agente pode pedir o trecho completo de volta com headroom_retrieve. É um projeto pessoal criado por Tejas Chopra, ex-engenheiro da Netflix, não um produto da Netflix.
O que os números realmente mostram
Em 30/09/2026, o repositório tinha 74.123 estrelas e licença Apache 2.0. No README, o teste do próprio projeto diz que um log caiu de 10.144 para 1.260 tokens, cerca de 8× menor, com o mesmo FATAL encontrado. O GIF ao lado desse texto mostra uma sessão do Claude Code, não o teste do log. Na imagem de abertura, outro teste reduz 55.957 a 24.340 tokens (57%) e a linha FATAL no item 67 permanece idêntica.
Na tabela Proof do README, quatro cenários sintéticos de agentes pouparam 21% (busca de código), 57% (incidente SRE), 42% (exploração do código) e 30% (triagem de issues) em tokens de entrada, em 30/09/2026. Não são contas reais medidas. Cache, preço do modelo e tokens de saída alteram o custo final. Se você usa assinatura fixa do Claude ou ChatGPT, a vantagem pode ser mais espaço no limite de uso, não uma mensalidade menor. Texto corrido, chats curtos e dados já densos quase não comprimem.
Instale o Headroom
Tenha Python 3.10+; com uv, a instalação isolada recomendada usa Python 3.13:
uv tool install --python 3.13 "headroom-ai[all]"Alternativa com pip:
pip install "headroom-ai[all]"O CLI headroom vem do pacote PyPI. O pacote npm headroom-ai é só o SDK TypeScript. Macs Intel podem precisar de Docker ou do ajuste onnxruntime.
Claude Code
Abra o terminal na pasta do seu projeto e rode:
headroom wrap claudeIsso inicia um proxy local e abre o Claude Code através dele. Para desfazer a configuração persistente:
headroom unwrap claudewrap também registra Serena para navegar pelo código no escopo do usuário. Para não instalar Serena, use headroom wrap claude --code-memory none.
Codex
No terminal do projeto:
headroom wrap codexO comando abre o Codex pelo proxy e registra a ferramenta MCP de recuperação. Para dispensar Serena: headroom wrap codex --code-memory none. Para reverter a integração persistente: headroom unwrap codex.
Cursor
headroom wrap cursorDeixe esse terminal aberto. O comando inicia o proxy e imprime as URLs. No Cursor, abra Settings → Models → OpenAI API Key → Advanced → Override Base URL. Cole a URL OpenAI indicada no terminal, normalmente http://localhost:8787/v1. Configure sua chave do provedor em Cursor; confira na tela se o modelo selecionado permite uma URL personalizada. O Cursor não recebe configuração automática como os dois CLIs.
Confira se funciona e meça no seu uso
Com o proxy rodando, em outro terminal:
headroom doctorheadroom dashboardheadroom savingsO painel abre em http://localhost:8787/dashboard. Faça uma tarefa real com muitos resultados de ferramentas e confira os tokens antes e depois. Um painel sem tráfego ainda não prova economia.
Para outro cliente, inicie headroom proxy --port 8787 e configure ANTHROPIC_BASE_URL=http://localhost:8787 ou OPENAI_BASE_URL=http://localhost:8787/v1 no ambiente do cliente. Para clientes MCP, headroom mcp install registra o servidor nos agentes detectados; use --agent claude para limitar a um agente. Mantenha suas credenciais habituais com o provedor.
Privacidade e preço
A compressão acontece localmente; seus prompts e arquivos não vão para servidores da Headroom Labs. O prompt comprimido ainda segue para o provedor de IA que você já usa. Segundo o README, um beacon anônimo fica ativo por padrão: envia proporções e contadores, não prompts, código ou caminhos de arquivos. Desative com HEADROOM_BEACON=off, DO_NOT_TRACK=1 ou --offline. O modelo Kompress pode ser baixado do Hugging Face no primeiro uso. Leia a política de confiança.
Todo o código do repositório é grátis sob Apache 2.0. A oferta paga é implantação e suporte gerenciados para equipes, com SSO, painel da organização e VPC. Não há preço público.
Perguntas rápidas
É grátis mesmo? Sim, o repositório e o uso local são gratuitos; o provedor de IA que você já usa pode cobrar à parte.
Muda as respostas? Pode mudar: compressão não garante identidade perfeita em toda tarefa. No teste GSM8K publicado pelo projeto, a acurácia foi 0,870 → 0,870 em 100 questões; isso não prova equivalência universal. Confira resultados importantes e recupere o original se precisar.
Funciona com minha assinatura Claude ou ChatGPT? Claude Code e Codex têm caminhos documentados; acesso por assinatura, login e limites dependem do cliente e do provedor. O ChatGPT no navegador não oferece esse ajuste de proxy. Não conte com redução da mensalidade fixa.
Meu código vai para a Headroom Labs? Não para comprimir. O conteúdo que sobra ainda vai ao provedor de IA configurado; veja a seção de privacidade.
É o headroom.js? Não. headroom.js é uma biblioteca de cabeçalhos de site que somem ao rolar a página.
Comentários
Ficou com alguma dúvida ou tem algo a acrescentar? Participe da conversa.
Sem precisar de conta. Clique em Entrar e escolha um nome para comentar.
Carregando a conversa…
Privacidade dos comentáriosDiretrizes para comentários