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

Caveman Proxy comprimindo a entrada do agente de IA antes de cada chamada
Resposta rápida

O Caveman Proxy é um reverse proxy local que comprime a ENTRADA do agente (saídas de ferramenta, logs, arquivos, JSON, schemas, histórico) antes de cada chamada ao provedor, rodando na sua máquina. A adoção é por troca de base URL para http://127.0.0.1:8787, sem mudar código. O ponto que importa pra quem tem medo de perder informação: o Content-Addressed Recovery guarda os bytes originais em SQLite local antes de qualquer substituição com perda, e retrieve(handle) devolve o original byte-exact. Num benchmark fixado de 54 execuções no Claude Code, foram 33,2% menos input tokens, passando em 18 de 18 checagens de resposta exata

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

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

O que foi medido Camada Número publicado
Benchmark fixado no Claude Code (54 execuções) Entrada 33,2% menos input tokens
Checagens de resposta exata no mesmo benchmark Entrada 18 de 18
JSON de 40 registros no anúncio do Caveman 2 Entrada de 16.098 para 1.091 tokens (93% menor)
Skill do Caveman Saída 65% menos output tokens em média

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

  1. 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

  1. 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

  1. 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

  1. 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! 😀

Perguntas frequentes

O Caveman Proxy funciona só com Claude Code ou dá pra usar com outros agentes?

O Caveman embrulha nativamente Claude Code, Codex, Gemini, Aider, OpenCode, Hermes e OpenClaw, cada um iniciado com caveman na frente do nome. Pra somar um agente novo à lista nativa, basta um perfil JSON em agents/profiles/, sem escrever código.

Dá pra usar o Caveman Proxy com LangChain, CrewAI ou outro framework fora da lista nativa?

Sim. Vercel AI SDK, LangChain, LiteLLM, OpenAI Agents, CrewAI e PydanticAI entram apontando o SDK ou framework pro proxy local via troca de baseURL, o mesmo princípio do base-URL-swap usado pelos agentes nativos.

Preciso pagar ou criar conta pra usar o Caveman Proxy?

Não. A compressão local funciona sem conta Caveman, com as chaves do próprio usuário e sem dependência de nuvem (local-first, BYOK). Os recursos pagos do Caveman Cloud, como ledger verificado e verificação de recibo, estão em preview de design partner e entram em lista de espera.

O Caveman Proxy é open source?

A licença é dividida: o runtime do proxy é BSL 1.1, source-available, mas não é Open Source pelos critérios da OSI antes da Change Date. Já a CLI, a skill e os SDKs cliente são MIT. Uso self-hosted de primeira parte é permitido; hospedar ou embarcar a ferramenta pra terceiros exige licença comercial.

Como eu recupero o conteúdo original depois que o Caveman Proxy comprime uma resposta?

Via retrieve(handle), que devolve o original byte-exact sob demanda, ou pelo servidor MCP do Caveman, que expõe a ferramenta caveman_retrieve. Sem query ela traz o original completo; com query, estreita o retorno pras seções mais relevantes usando BM25. Handle desconhecido sempre devolve erro, nunca um payload inventado.

Dá pra acessar o Caveman Proxy de outra máquina da rede?

Não. O servidor local escuta por padrão em 127.0.0.1:8787, restrito à interface de loopback, então só a própria máquina onde ele roda enxerga o proxy. É por isso que o caveman start precisa rodar no mesmo host do agente.



Escrito por | Matheus Battisti

Matheus Battisti
Fundador da Hora de Codar

Programador apaixonado pelo mundo das tecnologias, sempre buscando em aprender e se aprofundar em linguagens, frameworks e o que mais for necessário para executar um bom trabalho. Agora tem uma nova missão que é de passar seu conhecimento adiante para formar novos programadores e especializar mais os que já são.

Formações

Formação Vibe Coding

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

  • 474 aulas
  • 20 projetos
  • 39h 30min

Blog | Mais populares