Headroom: o editor entre você e o modelo

Trinta dias. Um projeto. 3,6 bilhões de tokens de entrada enviados à API. O número vem dos transcripts das minhas próprias sessões do Claude Code, não do slide de um fornecedor. Noventa e oito por cento voltaram do cache do provedor a um décimo do preço — e a requisição média ainda assim carregava meio milhão de tokens de contexto.

Meio milhão de tokens é um livro. Cada requisição reenvia o livro.

É isso que significa conversar com um modelo sem memória. É um mensageiro que leva um dossiê entre você e um especialista e, a cada visita, lê para ele o arquivo inteiro desde a primeira folha — a página nova e as quatrocentas anteriores —, porque nada fica guardado entre uma visita e outra. E o especialista cobra por palavra.

O Headroom propõe pôr um editor na porta.

O que é o editor

O Headroom é um proxy de código aberto (Apache 2.0) que roda na sua própria máquina. Você aponta o agente para http://127.0.0.1:8787 em vez da API; o proxy lê cada requisição, edita e repassa o resultado. Nada sai do seu computador além do que já sairia. Ele fala os formatos da Anthropic, da OpenAI e do Gemini, de modo que o mesmo processo atende Claude Code, Codex, Cursor, Aider e mais uma dúzia de agentes.

Para o Claude Code em particular, três peças chegam juntas:

• o proxy, o editor propriamente dito;
• um plugin, dois hooks que verificam, no início da sessão (e antes de cada comando de shell), se o proxy está vivo — e o sobem se não estiver;
• um servidor MCP, três ferramentas que o modelo pode chamar: headroom_compress, headroom_stats e a que importa, headroom_retrieve.

O que ele faz com o dossiê

Quatro movimentos, nesta ordem.

Ele lê antes de cortar. Um roteador de conteúdo classifica cada bloco da conversa — a saída de uma ferramenta, um log, um JSON, um arquivo-fonte, a sua própria prosa — e escolhe o compressor adequado. JSON recebe um compactador estrutural que preserva a forma e descarta a repetição. Logs e tabelas recebem compactação nativa do formato, sem perda. Código passa por uma etapa ciente da árvore sintática, que mantém assinaturas e descarta corpos que o modelo já viu. Prosa vai para um pequeno modelo treinado que conserva as frases que carregam peso. Blocos que aparecem duas vezes em turnos diferentes seguem uma vez só.

Todo corte deixa um recibo. É esta a parte que torna o resto aceitável. Quando um compressor descarta algo, ele guarda o original em um cofre SQLite local e deixa um marcador no lugar: <<ccr:hash>>. Se o modelo precisar depois do que foi cortado, chama headroom_retrieve com o hash e recebe o original de volta. O Headroom chama isso de CCR — compress, cache, retrieve. A contagem de recuperações é o sinal de alarme: se cresce, o editor está cortando coisas de que o especialista realmente precisava.

Ele nunca reescreve uma página que o especialista já decorou. Os provedores guardam em cache o prefixo de uma conversa e cobram um décimo pela parte que já têm. Um editor que reordena páginas antigas quebra esse cache e custa mais do que economiza. O Headroom acompanha qual prefixo o provedor já viu e o congela.

Ele deixa o catálogo de ferramentas na porta. Uma sessão do Claude Code com alguns servidores MCP pode carregar centenas de definições de ferramentas — esquemas que o modelo lê em toda requisição e usa em quase nenhuma. Com a busca de ferramentas ligada, só os nomes viajam; o esquema é buscado quando o modelo estende a mão para aquela ferramenta. Não é invenção do Headroom — é um recurso do Claude Code —, mas o proxy faz questão dele por um motivo que vale conhecer: no momento em que você define um ANTHROPIC_BASE_URL próprio, o Claude Code deixa de adiar os esquemas, a menos que ENABLE_TOOL_SEARCH=true também esteja definido. Passe por qualquer proxy sem essa variável e o seu contexto se enche de catálogo.

Dois modos, uma tensão

O editor pode ser tímido ou ousado.

No modo cache, o padrão, ele só toca no turno mais recente. Toda página anterior fica byte a byte como o provedor a guardou. Seguro, barato e — por desenho — pequeno: a maior parte de uma conversa longa é página antiga, e página antiga é intocável.

No modo token, ele pode voltar e reescrever turnos anteriores. O dossiê encurta; o cache do provedor para aquela requisição é quebrado e refeito. Troca-se uma falha de cache pontual por um arquivo permanentemente menor. A estimativa do próprio Headroom é que isso estende uma sessão em um quarto a um terço antes de o contexto lotar.

Aprendi a diferença do jeito honesto. Por quatro dias o proxy rodou em um projeto real em modo cache, por acidente — um processo iniciado à mão havia ignorado o modo que eu tinha configurado. Pouco mais de 700 milhões de tokens passaram por ele. O compressor de mensagens removeu 1,7 milhão: um quarto de um por cento. O painel anunciava, animado, milhares de dólares em “economia de cache” — que era o cache do provedor, anterior ao proxy, que não lhe deve nada. A única camada que fez força de verdade foi o catálogo de ferramentas: 29,6 milhões de tokens de esquemas mantidos fora da janela de contexto.

Um quarto de um por cento não é um veredito sobre o Headroom. É um veredito sobre rodá-lo no modo errado e confiar em um painel. Por isso o teste recomeça amanhã, em modo token, com as regras escritas antes.

A configuração, como fiz hoje

A CLI se instala do mesmo jeito em qualquer sistema — uma ferramenta Python 3.13 em ambiente próprio:

# 1. Install the CLI in its own environment (Linux, macOS, Windows).
uv tool install --python 3.13 "headroom-ai[all]"
#    or: pip install "headroom-ai[all]"

# 2. One command, every OS: a proxy that survives reboots,
#    with the test's guardrails. Linux -> systemd user service,
#    macOS -> launchd agent, Windows -> Task Scheduler.
headroom install apply \
  --preset persistent-service \
  --mode token \
  --protect-tool-results Read,Edit,Write \
  --env HEADROOM_TOOL_DESC_MAX_CHARS=200 \
  --env HEADROOM_LOG_FILE="$HOME/.headroom/logs/requests.jsonl" \
  --telemetry

# 3. Route Claude Code through it: writes env + hooks into
#    .claude/settings.local.json (--global: ~/.claude/settings.json).
#    Then check the wiring.
headroom init claude
headroom doctor

O passo 2 é o caminho portátil: headroom install apply cria um proxy que sobrevive a reinicializações e, de quebra, aplica as salvaguardas do teste. No Linux ele vira um serviço de usuário do systemd; no macOS, um agente do launchd; no Windows, uma entrada no Agendador de Tarefas (a ferramenta converte o preset de serviço por você). O passo 3 escreve ANTHROPIC_BASE_URL e ENABLE_TOOL_SEARCH no .claude/settings.local.json do projeto, junto com os hooks que mantêm o proxy vivo. O headroom doctor diz, em uma tabela, se o proxy está de pé, se o Claude está de fato roteado e se o seu shell o está contornando.

Por baixo do capô, no Linux, são três arquivos pequenos — e eu prefiro ser dono deles. Os ajustes vivem em um lugar só:

# ~/.headroom/proxy.env — every proxy setting lives here.
# The service reads it; nothing is configured anywhere else.
HEADROOM_MODE=token
HEADROOM_PROTECT_TOOL_RESULTS=Read,Edit,Write
HEADROOM_TOOL_DESC_MAX_CHARS=200
HEADROOM_LOG_FILE=/home/you/.headroom/logs/requests.jsonl
HEADROOM_TELEMETRY=on

O serviço os lê e reinicia o proxy se ele cair:

# ~/.config/systemd/user/headroom.service
# Enable: systemctl --user daemon-reload
#         systemctl --user enable --now headroom.service
[Unit]
Description=Headroom proxy (Claude Code context optimization, token mode)
Documentation=https://github.com/headroomlabs-ai/headroom
After=default.target
StartLimitIntervalSec=60
StartLimitBurst=10

[Service]
Type=simple
EnvironmentFile=%h/.headroom/proxy.env
ExecStart=%h/.local/bin/headroom proxy --host 127.0.0.1 --port 8787
Restart=always
RestartSec=2
OOMPolicy=continue

[Install]
WantedBy=default.target

E um wrapper abre o Claude através do proxy. O claude puro fica intocado de propósito — é o grupo de controle:

#!/usr/bin/env bash
# ~/.local/bin/clh — Claude Code through Headroom.
# Plain `claude` stays proxy-free on purpose: it is the control group.
# Usage: clh [claude args]   e.g. clh --resume, clh -c
systemctl --user is-active -q headroom.service \
  || systemctl --user start headroom.service
for _ in $(seq 1 30); do
  curl -sf -m1 http://127.0.0.1:8787/readyz >/dev/null && break
  sleep 0.5
done
exec env ANTHROPIC_BASE_URL=http://127.0.0.1:8787 ENABLE_TOOL_SEARCH=true \
  claude --dangerously-skip-permissions "$@"

O gêmeo para Windows é um script PowerShell no seu PATH; o proxy fica vivo pela tarefa agendada do passo 2:

# clh.ps1 — Windows twin of the Linux wrapper. Put it on your PATH;
# run `clh --resume`. The proxy itself is kept alive by the
# Task Scheduler entry that `headroom install apply` creates.
$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:8787"
$env:ENABLE_TOOL_SEARCH = "true"
claude --dangerously-skip-permissions @args

Se preferir não usar wrapper, é isto que o headroom init claude escreve no projeto — as mesmas duas variáveis, mais o hook:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",
    "ENABLE_TOOL_SEARCH": "true"
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "headroom init hook ensure --profile default",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

Uma nota sobre --dangerously-skip-permissions: essa flag é escolha minha, na minha máquina, onde o agente trabalha dentro de repositórios git que posso restaurar. Deixe-a de fora se essa não for a sua situação.

As regras do teste

Dois princípios, acordados antes de a primeira requisição passar.

Economizar o máximo, perder o mínimo — e saber o que se perdeu. Compressão com perda continua sendo perda; afirmar que nada é afetado seria desonesto. O que o teste exige é que toda perda seja aceitável (não altera o resultado do trabalho), previsível (as regras do que nunca é cortado são conhecidas de antemão) e auditável (o que foi cortado pode ser contado e recuperado).

Deixar a evidência decidir. Antes e depois são medidos na mesma fonte, e a regra para manter, aprofundar ou abandonar a configuração é escrita antes de os dados chegarem. O gráfico decide, não a impressão.

Na prática, as salvaguardas são estas:

E a medição, em três fontes que não dependem umas das outras: os transcripts do Claude Code, que registram o que a API de fato cobrou por requisição; o log de requisições do próprio proxy, que registra o que ele afirma ter feito; e o coletor de uso da assinatura, que registra quanto da cota semanal do plano foi realmente consumido. Dois projetos, três fases cada — sem proxy, modo cache, modo token —, com pelo menos cinco dias úteis na última.

A regra fica fixada agora, para que eu não possa dobrá-la depois: manter e aprofundar se os tokens cobrados por requisição caírem quinze por cento ou mais, se releituras e recuperações não subirem mais de um quinto e se a latência acrescentada pelo proxy ficar abaixo de quatro segundos no nonagésimo percentil. Fora disso, voltar ao modo cache ou à compactação sem perda — e dizer isso.

O que vem a seguir

O editor sentou-se na cadeira hoje à noite. Em alguns dias publico o que os recibos dizem: tokens por requisição em cada fase, leituras contra escritas de cache, até onde uma sessão se estende antes de lotar, quantas vezes o modelo pediu um original de volta e quanto o proxy custou em segundos. Se o editor merecer a cadeira, eu digo. Se não merecer, digo também.

Versões: Headroom 0.36.5, Claude Code 2.1.278, em setembro de 2026. Os números acima vêm de um projeto real em que trabalho; o projeto não é o assunto e não é nomeado.