Faça o seu agente de IA gastar menos tokens com as mesmas respostas

01Pra que serve

Cortar o que o agente lê antes de mandar pra IA. Num teste do projeto (investigar um incidente com logs), 55.957 tokens viraram 24.340, ou seja, 57% a menos.
Ligar no agente que você já usa com um comando só: headroom wrap claude, codex, copilot, aider, opencode, cline, goose e outros.
Ver num painel ao vivo quanto você está economizando, e tirar um relatório da economia com o seu próprio uso.
Encurtar também o que a IA escreve de volta, que também entra na conta (opcional, vem desligado).
A compressão é feita na sua máquina: o conteúdo dos prompts e dos arquivos não é mandado pra lugar nenhum pra ser comprimido.

02O que você precisa

Python 3.10 ou mais novo
Windows x86_64, Linux ou macOS (Apple Silicon ou Intel)
Um agente de código: Claude Code, Codex, Copilot, Aider…
A conta do agente que você já usa

03Passo a passo

Confira se o Python é 3.10 ou mais novo. No Windows, rode no PowerShell.
```
python --version
```
Instale o Headroom. Isso já traz o comando headroom no terminal. Se você usa uv, a documentação recomenda: uv tool install --python 3.13 "headroom-ai[all]".
```
pip install "headroom-ai[all]"
```
Veja se instalou direito. Tem que aparecer o número da versão.
```
headroom --version
```
Abra a pasta do seu projeto no terminal e ligue o Claude Code passando pelo Headroom. Ele sobe um proxy local e abre o Claude Code. Usa Codex? Troque claude por codex.
```
headroom wrap claude
```
Com o agente rodando, abra outro terminal e veja a economia ao vivo. O painel só funciona com o proxy ligado.
```
headroom dashboard
```
Quer o número que vale pra você, com o seu uso de verdade? Peça o relatório. Pra desfazer a ligação depois, use headroom unwrap claude.
```
headroom savings
```

04Exemplos de uso pra tirar proveito do Headroom

Investigar um erro com muito logOnde o Headroom mais economiza: logs grandes e saída de ferramentas. Cole no Claude Code aberto pelo headroom wrap claude

Investigue por que [DESCREVA O ERRO, ex.: o login falha às vezes] neste projeto.
Leia os logs em [CAMINHO DA PASTA DE LOGS] e rode [COMANDO DOS TESTES, ex.: npm test] pra reproduzir.
Me mostre a causa provável, o arquivo e a linha, e proponha a correção antes de mudar qualquer coisa.
Responda em português.

Entender um projeto grandeQuando o agente precisa ler muitos arquivos de uma vez

Leia a pasta [CAMINHO DA PASTA] e me explique em português como este projeto funciona: os módulos principais, por onde entra uma requisição e onde ficam as configurações.
Termine com uma lista dos 5 arquivos que eu devo ler primeiro, e por quê.

Comparar o antes e o depoisDepois de uma ou duas sessões, pra ver quanto economizou

headroom savings

Encurtar as respostas da IAOpcional: liga a redução do que o modelo escreve de volta (comando da documentação, pra Linux e Mac; antes de abrir o agente)

export HEADROOM_OUTPUT_SHAPER=1
headroom wrap claude

05Antes de usar

A economia depende do conteúdo. Nos testes do projeto ela vai de 21% a 57%. Texto corrido ou já enxuto quase não comprime, e conversa curta economiza pouco ou nada.
A economia nas respostas da IA (output) é uma estimativa, não uma medição, e vem desligada por padrão.
Vem ligada uma telemetria anônima: números da compressão, modelo usado e sistema. Segundo o projeto, nunca vão prompts, respostas, código ou caminhos de arquivo. Pra desligar, use a variável HEADROOM_BEACON=off ou DO_NOT_TRACK=1.
No Cursor, a ligação é manual. Os recursos que usam ONNX pedem processador com AVX2, e rede de empresa pode exigir configuração extra de certificado.
O código é grátis (Apache 2.0). Alguns recursos de empresa, como defesa contra prompt injection e escolha automática de modelo, são pagos. Você continua pagando a IA normalmente, só que por menos tokens.

Resumindo: instala com um comando, liga no agente com headroom wrap claude e acompanha no painel quanto deixou de gastar.

Seguir @alvim_ai Repositório oficial no GitHub

Todos os guias e prompts do Alvim