O que é o Caveman no OpenCode e quando vale a pena usar?

Fala aí, beleza? Apareceu um agente que responde feito homem das cavernas pra gastar menos token, e o projeto já é enorme no GitHub, mas o que ele faz de verdade dentro do OpenCode ainda aparece pouco explicado por aí

Aí bate a dúvida: isso é meme ou é ferramenta séria?

É ferramenta séria, com repositório, releases e até um documento de números honestos assumindo os próprios limites

Neste post eu te conto o que o Caveman faz de verdade, como ele encaixa no OpenCode, como instalar só nele e, principalmente, QUANDO vale a pena ligar (e quando ele só atrapalha)

Bora?

O que o Caveman faz com a resposta do agente

O Caveman é um projeto open source que funciona como uma camada de compressão da resposta do agente

A ideia é simples de entender: em vez de o modelo escrever "basically, what you really just need to do here is…", ele corta pro osso e entrega a substância

As regras do projeto mandam remover artigos, palavras de enchimento (just, really, basically, simply), gentilezas e hedging, aquele tom de "talvez, possivelmente, se eu não estiver enganado"

E o que NÃO pode ser tocado?

Formação Recomendada

Formação Agentes de IA

Domine a criação de Agentes de IA e Venda para Empresas

• 402 aulas
• 32 projetos
• 38h 19min

Conhecer formação

Os termos técnicos e os trechos literais

Código, comandos e mensagens de erro seguem exatamente como são, porque comprimir isso seria destruir a resposta em vez de encurtar ela

É compressão de estilo, não de conteúdo

Se você conhece minificação de JS, a analogia é boa: sai espaço em branco e nome longo, fica o comportamento igualzinho

O repositório oficial é o JuliusBrussee/caveman, e ele já passa de 94 mil estrelas no GitHub

Não é métrica de qualidade, mas é sinal de tração e de que muita gente tá olhando pro problema de resposta verbosa

Por que isso encaixa no OpenCode

Antes de falar de ativação, vale situar o terreno

O OpenCode é um agente de codificação open source pra terminal, feito pelo time do SST, com repositório sst/opencode

E ele tem uma característica que faz toda a diferença aqui: implementa o padrão Agent Skills de forma nativa

"Como assim nativo?"

O OpenCode expõe uma ferramenta skill que lista as skills instaladas por nome e descrição logo na inicialização, e só carrega as instruções completas quando o modelo decide que aquela skill se aplica

Carregamento sob demanda, sem entupir o contexto de cara

Uma skill, no fim, é uma pasta com um SKILL.md dentro

Se você ainda tá decidindo quando usar skill ou MCP, esse é exatamente o tipo de caso que mora do lado da skill: comportamento e instrução, não integração com serviço externo

E tem o segundo caminho, que é onde o Caveman se agarra de verdade: no OpenCode as instruções também podem vir do AGENTS.md e de arquivos apontados no campo instructions do opencode.json (que aceita caminhos, globs e URLs)

Sem AGENTS.md na raiz do projeto, o OpenCode cai no CLAUDE.md

Ou seja: skill nativa pra carregar sob demanda, e arquivo de regras pra valer sempre

O Caveman usa os dois

O que muda no comportamento do agente depois de ativar

Aqui tá a parte que interessa no dia a dia

O suporte oficial ao OpenCode entrou na versão 1.8.0 do Caveman, e a ativação é automática por padrão

Traduzindo: o agente já responde em caveman desde a primeira mensagem, você não precisa ficar chamando /caveman a cada sessão nova

Os comandos reconhecidos dentro do OpenCode são estes:

• /caveman
• /caveman-commit
• /caveman-review
• /caveman-compress

Além deles, o projeto aceita gatilhos em linguagem natural, então dá pra pedir a mudança de estado conversando mesmo

E por baixo do capô?

O plugin usa hooks do próprio OpenCode

O hook session.created grava o modo padrão em ~/.config/opencode/.caveman-active

Já o tui.prompt.append observa o que você digita e troca o estado quando vê os comandos

Então o "ligado/desligado" não é mágica, é um arquivinho de estado no disco mais dois ganchos do agente

Se você curte esse papo de mudar o comportamento padrão do agente sem ficar repetindo instrução, o modo YOLO no OpenCode segue a mesma lógica de configuração que passa a valer sozinha

Níveis do Caveman: lite, full e ultra (e as variantes wenyan)

O Caveman não é liga/desliga só

O SKILL.md do projeto lista níveis de intensidade, e o padrão é o full

As variantes wenyan aparecem listadas no SKILL.md do repositório oficial, e é lá que dá pra conferir o comportamento de cada uma antes de sair alternando

E o número de economia que o projeto declara é UM só, global (já já eu chego nele), não uma tabelinha por intensidade

Como instalar o Caveman só no OpenCode

O instalador do Caveman cobre vários agentes, mas dá pra mirar só no OpenCode

1. Rode a instalação apontando só pro OpenCode

npx -y github:JuliusBrussee/caveman -- --only opencode

2. Se preferir não usar npx, clone o repositório e rode o instalador na mão

node bin/install.js --only opencode

O erro comum deste passo: rodar o instalador sem o --only opencode e ele sair mexendo em configuração de outros agentes que você nem queria tocar

3. Confira o que o instalador mexeu no seu opencode.json

Ele inclui ./plugins/caveman/plugin.js no array plugin

4. Confira o AGENTS.md

O instalador acrescenta o conjunto de regras usando comentários marcadores, e o ruleset sempre-ligado fica em ~/.config/opencode/AGENTS.md

Esse detalhe não é decoração: o ruleset mora ali justamente pra valer mesmo se o plugin não carregar

O erro comum deste passo é achar que o plugin sozinho garante o comportamento

Não garante

Plugin cuida do estado e dos comandos, o arquivo de regras é quem segura o comportamento quando o plugin falha

Instalou e não funcionou? O que a comunidade está relatando

Tome cuidado aqui, porque a instalação no OpenCode acumula relato de problema em issues abertas no repositório oficial

Sintomas que aparecem por lá:

• OpenCode não inicia depois de instalar (issue #422)
• Erro ENOENT copiando caveman-compress.md, porque o arquivo está ausente no repositório (issues #426 e #482)
• Instalação por npx incompleta, sem criar ~/.config/opencode/agents e ~/.config/opencode/skills (issue #463)

E qual é a causa de fundo?

O próprio projeto conta na release v1.9.0, que tem o título "Rock pinned. Rock verified. opencode rock work now."

Até ali, o plugin do OpenCode simplesmente NUNCA carregava

O motivo é ótimo pra quem gosta de bastidor: o OpenCode roda plugins dentro de um binário Bun compilado, onde require() de arquivos em disco e import() de CJS falham em silêncio

Falha em silêncio é o pior tipo de falha, você jura que instalou e nada acontece

A v1.9.0 foi a primeira versão testada contra um runtime real do OpenCode

Depois disso veio a v1.9.1, a mesma release que se chama "65%, honestly" e unificou o número de economia do projeto

Ela consertou outro caso chato: instalar pra OpenCode com --force apagava um AGENTS.md legado em vez de migrar ele

Agora migra

Prevenção que vale pra todo mundo: use o repositório oficial e confira a versão antes de sair debugando

Existem ports e pacotes de terceiros circulando, como anthonystepvoy/caveman-opencode, dantesCode/caveman-opencode-plugin e o pacote npm @mumme-it/opencode-caveman

São repositórios e contas distintas de JuliusBrussee/caveman, então se você instalou de um deles e algo quebrou, o problema pode nem estar no projeto original

Quando usar o Caveman no OpenCode (e quando ele atrapalha)

Compensa quando:

• Você passa horas em sessão longa de terminal e a resposta gigante vira scroll infinito
• O modelo tá verboso demais pro seu gosto e você só quer o comando e o diagnóstico
• Leitura rápida importa mais que texto redondinho, tipo review e commit

Agora a parte que o próprio projeto documenta e que quase ninguém repete quando compartilha o link

O Caveman só encolhe tokens de SAÍDA

Entrada e raciocínio ficam intactos

E a própria skill soma cerca de 1 mil a 1,5 mil tokens de entrada por turno de overhead, porque as regras precisam estar no contexto pra valer

Sabe o que isso significa?

Em carga já enxuta, em conversa curtinha, o saldo pode ficar LÍQUIDO NEGATIVO

Você paga overhead de entrada pra economizar numa saída que já era pequena

O próprio projeto diz que, na prática, o ganho principal é legibilidade e velocidade

Economia é consequência, não a promessa

Vale a pena ativar o Caveman?

A economia declarada hoje pelo projeto é de 65% de redução média de tokens de saída

E olha a origem do número, que é o que interessa: ele vem de um benchmark de 10 prompts versionado no repositório

Dez prompts

É um sinal, não é lei da física pro seu projeto

Esse é justamente o valor que foi unificado na v1.9.1, a release "65%, honestly", o que já diz bastante sobre a postura do projeto com os próprios números

Meu veredito por perfil:

• Sessão longa e verbosa no terminal: liga, o ganho de leitura sozinho já paga
• Uso curto e pontual: provavelmente não compensa, você entra no cenário de saldo negativo que o projeto assume
• Ambiente de trabalho crítico: vá com calma, porque o histórico de instalação no OpenCode ainda tem issues abertas de plugin que não carrega e arquivo ausente

O risco de instalação instável é real e tem que ser declarado, não adianta pintar tudo de topzera

Mas repara que ele é reversível: no pior caso, você tira a entrada do array plugin e limpa o bloco entre os marcadores do AGENTS.md

Conclusão

Recapitulando o que ficou de pé:

O Caveman é um projeto open source que comprime o ESTILO da resposta do agente, cortando artigo, filler, gentileza e hedging, e preservando termo técnico, código e mensagem de erro

No OpenCode ele entrou oficialmente na v1.8.0, ativa por padrão, com comandos como /caveman e /caveman-review, hooks session.created e tui.prompt.append, e o ruleset sempre-ligado em ~/.config/opencode/AGENTS.md

Os 65% são de saída, num benchmark de 10 prompts, com overhead de entrada assumido pelo próprio projeto

Próximo passo concreto se você quiser testar: instala só no OpenCode com --only opencode e alterna entre lite, full e ultra até achar o ponto de leitura confortável pro SEU jeito de trabalhar

E acompanha as releases do repositório oficial, porque esse é daqueles projetos que muda rápido e a versão que você instalou hoje pode ser exatamente a que consertou o seu problema 😀

Até o próximo post!