Headroom: Como Cortar Até 95% dos Seus Tokens Sem Mudar as Respostas
Cada chamada de ferramenta que seu agente faz, cada log que lê, cada chunk de RAG e cada arquivo que você mete no contexto: você paga por tudo, e a maior parte é boilerplate. Headroom é uma camada open-source que fica entre seu agente e o modelo, e comprime tudo antes de chegar ao LLM. A promessa é direta: as mesmas respostas, uma fração dos tokens.
O projeto é de Tejas Chopra, um engenheiro da Netflix, e vem se movimentando rápido: já é uma das ferramentas para developers mais estreladas desse espaço. É Apache 2.0, roda localmente (seus dados nunca saem de sua máquina) e é agnóstico de modelo: Claude, Codex, Cursor, Aider, Copilot no lado do agente, e Anthropic, OpenAI, Bedrock, Vertex, Azure ou mais de 100 provedores via LiteLLM no backend.
¿Primeira vez com a economia de tokens? Em O que são tokens em IA e por que cobram por eles está a base: o que é exatamente um token, por que se paga a conversa inteira em cada turno, e como contá-los de graça antes de pagá-los.
O que faz, concretamente
Headroom intercepta o volumoso —saídas de ferramentas, logs, leituras de banco de dados, resultados de RAG, leituras de arquivos, histórico de conversa— e passa por um pipeline de compressores especializados antes de chegar ao modelo:
- SmartCrusher para JSON: conserva os primeiros e últimos itens, os erros, as anomalias e os matches de relevância, e esmaga o meio repetitivo.
- CodeCompressor, com consciência de AST para Python, JS, Go, Rust, Java e C++.
- Kompress-base, o modelo próprio do projeto no HuggingFace, treinado sobre agentic traces, para texto plano.
- Um roteador de ML para compressão de imagens.
A decisão de design chave é que a compressão é reversível. Headroom cachea os originais localmente (o sistema CCR — Compress-Cache-Retrieve) e injeta uma ferramenta headroom_retrieve para que o modelo possa recuperar os dados completos se decidir que lhe falta algo. Esse é o mecanismo por trás da promessa de “as mesmas respostas”: nada é descartado de forma permanente, simplesmente fica fora do prompt até que faça falta.
Quatro formas de colocá-lo no seu stack
Essa é a parte que torna Headroom fácil de testar. Você não precisa se comprometer com uma arquitetura: escolha a integração que coincida com como você já trabalha.
Proxy (zero mudanças de código). Você o inicia e aponta a URL base do seu agente para ele:
pip install "headroom-ai[all]"
headroom proxy --port 8787
# Claude Code
ANTHROPIC_BASE_URL=http://localhost:8787 claude
# Qualquer cliente OpenAI
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
Agent wrap, um único comando: headroom wrap claude|codex|cursor|aider|copilot.
Library, inline em Python ou TypeScript:
from headroom import compress
result = compress(messages, model="claude-sonnet-4-5-20250929")
# result.messages: mesma estrutura, muito menos tokens
MCP server, para qualquer cliente MCP: headroom mcp install expõe headroom_compress, headroom_retrieve e headroom_stats como ferramentas.
Os números, e de onde saem
O título do Headroom é 60–95% de redução de tokens com a qualidade das respostas preservada. Esses são os benchmarks próprios do projeto e, é preciso reconhecer, são reproduzíveis: você clona o repo e roda você mesmo a suite de evals. Os mais destacados: 94.9% de compressão com 98.2% de recall em um benchmark de extração de artigos, e 76.3% de compressão em um teste de agente multi-ferramenta onde todos os achados objetivo seguiam sendo recuperados.
O que vale a pena marcar é como o projeto lida com seu recurso de tokens de saída —cortar o que o modelo escreve de volta, não apenas o que você manda—. Em vez de citar um percentual com falsa segurança, o README é honesto em que esse economia não pode ser observada diretamente: relata uma estimativa com um intervalo de confiança de 95% (por exemplo ~32%, com um intervalo declarado) e oferece uma via de medição real: deixe 10% de suas conversas sem comprimir como grupo de controle com HEADROOM_OUTPUT_HOLDOUT=0.1 e o dashboard etiqueta o número como measured em vez de estimated. Esse tipo de ponderação no próprio README de um projeto v0.x é um bom sinal.
Onde não encaixa
A compressão não é magia grátis, e o projeto diz isso de frente. O texto denso e único, ou o código novel, comprimem muito menos: o próprio benchmark de exploração de codebase do Headroom apenas chegou a 47%, porque simplesmente há menos boilerplate para tirar. E a ida e volta de comprimir/recuperar adiciona uma peça móvel: se o modelo abusa de headroom_retrieve, você recupera parte da economia de volta, então vai querer medir sobre seu próprio tráfego em vez de confiar no número do título.
Onde brilha é no perfil oposto: agentes que disparam muitas ferramentas e ingerem saídas estruturadas grandes (resultados de busca, respostas de API, dumps de log), pipelines de RAG metendo chunks repetitivos, e sessões automatizadas de longa duração onde os mesmos arquivos e histórico são reenviados turno após turno.
Vale a pena testá-lo
É um projeto v0.x se movimentando rápido, então fixe uma versão, leia o changelog e teste antes de produção. Mas a fricção para testá-lo é realmente baixa —um proxy e uma mudança de URL base— e a premissa é sólida: em um monte de workflows de agentes o gargalo não é o modelo, é o volume de contexto de baixo valor que você está pagando para mandar. Headroom é uma tentativa limpa e honesta de consertar isso, de alguém que claramente pensa em custo em escala.
Você já está medindo quantos tokens de seu pipeline são boilerplate, ou ainda está pagando a conta completa sem olhar?