Caveman Proxy: o que muda quando o agente lê menos antes de cada chamada?

Fala aí, beleza? Todo mundo olha pro tamanho da RESPOSTA do agente, mas a conta que cresce em silêncio é a da entrada

Saída de ferramenta, log gigante, JSON de API, schema, arquivo inteiro, histórico da conversa: tudo isso viaja junto em cada chamada ao provedor

O Caveman Proxy entra exatamente aí

Ele é um reverse proxy local que comprime o que o agente lê antes de a requisição sair da tua máquina: uma camada de compressão de input, rodando local

E a promessa que deixa o papo interessante pra quem tem pavor de perder detalhe: os bytes originais ficam guardados ANTES de qualquer substituição com perda, pra recuperar o original byte a byte quando o agente precisar 🙂

De onde veio: o Caveman 2 e o repositório do projeto

O Caveman 2 é a release que trouxe o proxy e o motor de compressão de entrada

A tag v2.1.0 foi publicada em 16 de agosto de 2026, então estamos falando de coisa fresca, saída do forno faz poucos dias

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 118 aulas
• 4 projetos
• 9h 33min

Conhecer formação

O projeto é mantido no repositório JuliusBrussee/caveman

E tem um detalhe de bastidor que ajuda a não se perder na hora de pesquisar: os repositórios anteriores do autor (caveman-code, cavemem e cavekit) estão marcados como Frozen

O desenvolvimento ativo migrou pro repo caveman

Ou seja: se tu cair num desses repos congelados e achar que o projeto morreu, não é isso, é só endereço velho

Quanto o corte vale na prática (e o que o benchmark mediu)

Número sem contexto não vale nada, então vamos ao que está publicado

O benchmark do projeto é fixado em 54 execuções no Claude Code

Nesse recorte, o Caveman usou 33,2% menos input tokens reportados pelo provedor do que o Claude Code direto

E aqui vem a parte que interessa mais que a economia: passou em 18 de 18 checagens de resposta exata

Economizar quebrando a resposta seria fácil, o difícil é economizar e a resposta continuar certa

Tem também um exemplo publicado no anúncio do Caveman 2: um JSON de 40 registros saiu de 16.098 para 1.091 tokens, 93% menor, byte-safe e recuperável

Repara na última linha, porque ela costuma virar confusão

Os 65% são da SKILL, que é a camada de saída, coisa diferente do proxy

São dois lados do mesmo problema: a skill mexe no que o agente escreve, o proxy mexe no que o agente lê

E já que o assunto é skill, vale lembrar que detalhe pequeno de arquivo muda comportamento, tipo o idioma em que a skill é escrita

Por que "comprimir" aqui não significa perder o detalhe:

Essa é a pergunta que trava todo mundo

Se a camada corta pedaço do log, do JSON e do arquivo, o que garante que o agente não vai alucinar em cima do que sobrou?

A resposta do projeto se chama CCR

Antes de qualquer substituição com perda, os bytes originais são armazenados localmente, num banco SQLite em ~/.caveman/ccr.db

O que fica no lugar do conteúdo é um handle

E esse handle é endereçado por conteúdo: ele deriva dos próprios bytes, então a mesma entrada gera sempre o mesmo handle, e o handle sozinho já basta pra buscar o original de volta

É como um número de guarda-volumes que foi carimbado a partir do que tem dentro da mochila, não sorteado na hora

A recuperação é retrieve(handle), que devolve o original byte-exact sob demanda

Mas o pedaço que eu acho MESMO bem pensado é a garantia dura do desenho

Um resultado com perda (a classe S4) só é emitido se o original foi armazenado com sucesso

Se não houver onde armazenar, o motor simplesmente não comprime e repassa o payload intacto

Ou seja: o sistema prefere gastar teu token a te entregar um corte que não dá pra desfazer

E tem mais um guarda-corpo: handle desconhecido devolve ERRO, nunca um payload inventado

Isso importa demais num agente, porque o pior cenário não é perder informação, é receber informação plausível e falsa no lugar dela

Como colocar o Caveman Proxy para rodar:

Bora ver na prática?

A sequência abaixo é só o que está documentado, sem invenção de flag no meio

1. Confere o Node.js

O instalador exige Node.js 18 ou superior

E ele é idempotente, então rodar de novo é seguro, não vai destroçar a instalação anterior

O erro comum deste passo: rodar em Node antigo que sobrou de outro projeto e culpar a ferramenta pelo erro de instalação

2. Instala a CLI e roda o setup

npm install -g @caveman-ai/cli && caveman setup --install

O erro comum deste passo: parar no npm install e achar que acabou, sem rodar o setup --install

3. Sobe o proxy local

caveman start

O servidor escuta por padrão em 127.0.0.1:8787, restrito à interface de loopback

O erro comum deste passo: tentar acessar de outra máquina da rede, sendo que ele é somente loopback

4. Inicia o agente já roteado

caveman claude

No lugar de claude também entram codex, gemini, aider, opencode, hermes e openclaw

O erro comum deste passo: abrir o agente do jeito de sempre, por fora do caveman, e depois estranhar que o consumo não mudou nada

5. Entendeu a lógica? A adoção é troca de endereço

Essa é a parte que confunde mais gente

A forma de adoção é base-URL-swap: tu aponta o agente pro endereço local (http://127.0.0.1:8787) e o tráfego passa pelo Caveman sem mudança de código

O erro comum deste passo: ficar caçando um menu de configuração DENTRO do agente

Não tem chave secreta escondida, a mudança é de base URL, e é isso

Quem ganha com essa camada (e como encaixar no seu setup)

Tem três situações bem diferentes aqui, se liga

1. Tu usa um dos agentes nativos

O Caveman já embrulha nativamente claude, codex, gemini, aider, opencode, hermes e openclaw

Nesse caso é o cenário mais preguiçoso possível (e isso é bom!): instala, sobe o proxy, chama o agente pelo caveman e segue a vida sem tocar em uma linha de código

2. Tu está fora da lista nativa

Aqui entram os SDKs e frameworks: Vercel AI SDK, LangChain, LiteLLM, OpenAI Agents, CrewAI e PydanticAI

A porta de entrada é a mesma, trocar a baseURL pro proxy local

E se tu quer um agente novo embrulhado direto, acrescentar um é mudança de DADO, não de código: um único perfil JSON em agents/profiles/

3. Tu trabalha em host MCP

O servidor MCP do Caveman expõe cinco ferramentas: caveman_compress, caveman_retrieve, caveman_stats, caveman_toon_encode e caveman_toon_decode

A estrela aqui é a caveman_retrieve

Sem query, ela devolve o original completo, byte-exact

Com query, ela estreita o retorno pras seções mais relevantes usando BM25, o que evita trazer um arquivo inteiro de volta só pra ler um trecho

E tem um detalhe de arquitetura que amarra tudo: por padrão o MCP abre o MESMO store compartilhado que a CLI e o proxy escrevem, o ~/.caveman/ccr.db

Na prática isso significa que o agente consegue recuperar um detalhe que o proxy elidiu durante uma requisição em streaming

Agora, se tu não quer nada tocando o disco, existe a alternativa efêmera: CAVEMAN_MCP_EPHEMERAL=1 usa um store em memória, e os handles somem no fim da sessão

Tome cuidado com essa escolha, porque store efêmero e recuperação depois da sessão não combinam, né?

Licença, custo e o que ainda não está aberto

A parte boa primeiro: a compressão local funciona sem conta Caveman

É local-first e BYOK, tu usa tuas próprias chaves e não fica dependente de nuvem nenhuma pra comprimir

Agora a parte que exige leitura atenta antes de levar pra produção: a licença é dividida

O runtime do proxy é BSL 1.1, que é source-available e NÃO é OSI Open Source antes da Change Date

Já a CLI, a skill e os SDKs cliente são MIT

Sob a BSL 1.1, uso em produção self-hosted de primeira parte é permitido

Mas uso hospedado, gerenciado ou embarcado por terceiros exige licença comercial

Traduzindo pro dia a dia: rodar na tua infra pro teu produto é uma coisa, revender isso embutido é outra bem diferente

E sobre os recursos pagos, o Caveman Cloud (ledger verificado, rollout com gate de eval, verificação de recibo) está em preview de design partner

Os planos pagos entram em lista de espera e a assinatura automática de recibo segue desabilitada

Vale testar agora?

A proposta é bem clara: economia de input com fidelidade garantida por armazenamento prévio dos bytes

E o desenho é honesto no ponto que mais importa, porque ele prefere NÃO comprimir a comprimir sem recuperação

Pra quem tem medo de perder informação, essa inversão é o argumento inteiro

O próximo passo concreto é simples: instala, roda o caveman start, aponta teu agente e compara o consumo de input numa tarefa que tu já conhece de cor

Esse é o mesmo raciocínio de comparar numa tarefa que você já conhece, com uma referência sua pra medir contra

Depois confere o essencial: a resposta continuou exata?

Só lembra de duas coisas antes de sair colocando isso no fluxo de produção do time

O projeto é recente, a release do Caveman 2 é de agosto de 2026

E a decisão de uso em produção passa por ler a licença com calma, não por confiar na vibe

Bora testar e trocar uma ideia depois?

Até o próximo post! 😀