Repolode
Enviar
headroomlabs-ai

headroomlabs-ai/headroom

Comprime saídas de ferramentas, logs, arquivos e trechos de RAG antes de chegarem a um LLM, como biblioteca, proxy ou servidor MCP.

Ver no GitHubSite
Estrelas
76,105
Forks
5,915
Issues abertas
482
Último commit
há 3 dias

O que é?

Headroom é uma camada de compressão de contexto para agentes de IA e aplicações com LLM. Ela comprime saídas de ferramentas, logs, trechos de RAG, arquivos e histórico de conversas antes que sejam enviados ao modelo, e a compressão é executada localmente na máquina do usuário. Um roteador de conteúdo identifica o tipo de cada payload: JSON é encaminhado ao SmartCrusher, código-fonte ao CodeCompressor, que leva em conta a AST, e prosa ao modelo Kompress-v2-base.

A ferramenta pode ser usada como biblioteca inline em Python ou TypeScript por meio de compress(messages), como proxy drop-in que não exige alterações no código, com headroom wrap para agentes de programação como Claude Code, Codex, Cursor e Aider, ou como servidor MCP. A compressão é reversível: os originais ficam em cache local, e o modelo pode recuperá-los sob demanda.

A economia varia conforme o payload. Os benchmarks do projeto mostram uma redução de 21% a 57% no número de tokens em workloads de agentes de exemplo, e saídas repetitivas de JSON e logs são muito mais comprimidas. Prosa e textos que já são densos têm pouca redução.

Recursos principais

  • 01Roteamento por tipo de conteúdo que escolhe um compressor para JSON, código ou prosa.
  • 02Compressão reversível, com os originais armazenados em cache local e disponíveis para recuperação sob demanda.
  • 03Proxy que não exige alterações no código e wrappers de um comando para agentes de programação populares.
  • 04Bibliotecas para Python e TypeScript com compress() para uso inline.
  • 05Servidor MCP com ferramentas de compressão, recuperação e estatísticas.
  • 06Processamento local, para que o conteúdo de prompts e arquivos não seja enviado a um serviço para compressão.

Casos de uso

  • Reduzir custos com tokens em agentes de programação como Claude Code ou Cursor durante sessões longas com muitas saídas de ferramentas.
  • Comprimir dumps de logs ou resultados grandes de buscas em JSON antes de enviá-los a um modelo para depuração.
  • Reduzir o tamanho de trechos recuperados via RAG em um pipeline existente com LangChain ou LiteLLM.
  • Encaminhar vários agentes por meio de um proxy e uma camada de memória compartilhados.

Início rápido

  1. 1

    Instale a CLI com uv

    uv tool install --python 3.13 "headroom-ai[all]"
  2. 2

    Ou instale o pacote Python com pip

    pip install "headroom-ai[all]"
  3. 3

    Inicie o proxy drop-in na porta 8787

    headroom proxy --port 8787
  4. 4

    Verifique a instalação com a verificação de integridade

    headroom doctor

Antes de usar

  • A economia varia bastante; textos em prosa e saídas que já são densas quase não são comprimidos.
  • Os benchmarks de compressão do README são autorrelatados e executados em cenários específicos com dados predefinidos.

Tópicos

#llm#context-window#token-optimization#rag#mcp#coding-agents#proxy#prompt-engineering#agent#ai

Perguntas frequentes

O que é headroom?
Comprime saídas de ferramentas, logs, arquivos e trechos de RAG antes de chegarem a um LLM, como biblioteca, proxy ou servidor MCP. Headroom é uma camada de compressão de contexto para agentes de IA e aplicações com LLM. Ela comprime saídas de ferramentas, logs, trechos de RAG, arquivos e histórico de conversas antes que sejam enviados ao modelo, e a compressão é executada localmente na máquina do usuário. Um roteador de conteúdo identifica o tipo de cada payload: JSON é encaminhado ao SmartCrusher, código-fonte ao CodeCompressor, que leva em conta a AST, e prosa ao modelo Kompress-v2-base.
headroom é gratuito? Qual é a licença?
headroom é open source sob a licença Apache-2.0. Confira os termos da licença antes de usá-lo em produtos comerciais.
headroom ainda é mantido?
Manutenção ativa. O último commit de headroom foi em 17 de out. de 2026.
Para que posso usar headroom?
Reduzir custos com tokens em agentes de programação como Claude Code ou Cursor durante sessões longas com muitas saídas de ferramentas. Comprimir dumps de logs ou resultados grandes de buscas em JSON antes de enviá-los a um modelo para depuração. Reduzir o tamanho de trechos recuperados via RAG em um pipeline existente com LangChain ou LiteLLM. Encaminhar vários agentes por meio de um proxy e uma camada de memória compartilhados.
Como instalar headroom?
Instale a CLI com uv: uv tool install --python 3.13 "headroom-ai[all]" Ou instale o pacote Python com pip: pip install "headroom-ai[all]" Inicie o proxy drop-in na porta 8787: headroom proxy --port 8787 Verifique a instalação com a verificação de integridade: headroom doctor
Onde consigo headroom?
O código-fonte e as instruções de instalação estão no GitHub: https://github.com/headroomlabs-ai/headroom

Resumo gerado por IA a partir do README do projeto. As estatísticas do GitHub são atualizadas diariamente.

Projetos relacionados