Caveman: como instalar a skill e o proxy que cortam tokens no Claude Code, Codex e Cursor

O Caveman (JuliusBrussee/caveman, Apache-2.0, 109.342 estrelas em 03/10/2026) tem duas peças:

• a skill (a "pedra pequena"): um arquivo de regras que faz o agente responder curto. Código, comandos, caminhos e mensagens de erro ficam intactos; só some o "enchimento" da resposta.
• o proxy (a "pedra grande"): um CLI que roda na sua máquina, entre o agente e o provedor, e encolhe o que o agente lê (logs, saída de teste, JSON, diffs). O original fica guardado e o agente pode pedir de volta.

A descrição do repo promete "65% menos tokens". Quem mediu de fora achou outra coisa: a JetBrains testou só a skill em 86 tarefas reais no Claude Code e mediu 8,5% menos tokens de saída, sem mudança de qualidade detectável (p = 0,82). O próprio README admite que esse número foi o motivo para criar o proxy, porque a maior parte da conta de um agente é leitura, não escrita.

No benchmark do próprio repo, o proxy levou 54 execuções no Claude Code de 885.793 para 591.673 tokens de entrada (-33,2%), com 18 de 18 respostas certas (intervalo de 95%: 14,6% a 48,5%; um caso, HTML, piorou 9,9%). O README avisa que os dados brutos ainda não estão publicados: é um relatório fixado, não uma reprodução pública.

• Node.js instalado (node -v). O instalador completo pede Node 22.13+; testei com Node 24 no Windows.
• Um agente: Claude Code, Codex ou Cursor (o README lista 30+ agentes).
• Para o proxy: permissão para instalar um pacote npm global e baixar os binários do caveman setup.

Claude Code

Skill (1 comando, sem conta, sem API key):

npx skills add JuliusBrussee/caveman -g

Ou como plugin:

claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

No meu teste (03/10/2026, num projeto vazio), o instalador copiou 22 skills (caveman, ultracave, megacave, caveman-commit, caveman-review, caveman-compress, caveman-stats e outras) e avisou: "Review skills before use; they run with full agent permissions."

Codex

npx skills add JuliusBrussee/caveman -a codex -g

Depois, dentro da sessão:

/caveman

Atenção: no Codex o hook de shrink do proxy fica desligado, porque o runtime do Codex recusa a reescrita (openai/codex#18491). A skill funciona normalmente.

Cursor

Por sessão:

npx skills add JuliusBrussee/caveman -a cursor -g

Sempre ligado (grava .cursor/rules/caveman.mdc no seu repositório):

npx skills add JuliusBrussee/caveman -a cursor -g --with-init

O proxy (onde está a economia de leitura)

npm install -g @caveman-ai/cli && caveman setup --install
caveman claude        # ou: caveman codex · caveman gemini · ...

Importante: sem o caveman setup --install, o proxy só repassa o texto. No meu teste, caveman shrink -- git log sem setup respondeu "engine unavailable; passthrough — run caveman setup" e não encolheu nada.

• /caveman liga a voz curta; stop caveman (ou normal mode) desliga.
• /ultracave corta mais (é a versão que mediu -35% no eval do repo).
• /caveman-commit escreve o commit em uma linha; /caveman-review dá um achado por linha.
• /caveman-compress CLAUDE.md encolhe o arquivo de memória e guarda o original.
• Com o proxy: caveman learn lê o histórico do seu agente localmente e mostra para onde seus tokens vão, do maior para o menor.

O próprio README diz que o teste na sua máquina vale mais que qualquer número da página:

caveman trial -- claude
caveman trial report

Isso roda uma sessão real com e sem caveman e mostra a diferença. Se você já ligou o caveman claude, desligue antes com caveman disable claude (e religue depois com caveman enable claude). Para o histórico: caveman stats; dentro do Claude Code: /caveman-stats.

• "O agente não ficou curto": digite /caveman (em alguns agentes a skill é por sessão). No Cursor, use --with-init para ficar sempre ligado.
• "O proxy não economizou nada": rode caveman setup --install; sem ele, é passthrough.
• Windows: o caveman shrink recusou o npm.cmd ("cannot safely launch non-Node Windows command shim"); com executáveis nativos (git) funcionou.
• Instalação quebrou: o README sugere abrir o agente dentro do repo do caveman e pedir: "Read CLAUDE.md and INSTALL.md, install caveman for me."
• Desinstalar: npx -y github:JuliusBrussee/caveman -- --uninstall.

• Pule se você paga por requisição, não por token (ex.: requisições premium do Copilot): resposta curta é a mesma requisição.
• As regras da skill entram como ~1.000 tokens de entrada em toda chamada; em perguntas curtas, pode custar mais do que economiza.
• Telemetria do CLI vem ligada por padrão (ID aleatório, IP, contagem de tokens; nunca prompts, código ou caminhos). Para desligar:

caveman telemetry off

(ou DO_NOT_TRACK=1). A skill sozinha nunca envia nada. - O benchmark do proxy é do próprio repo e ainda sem reprodução pública. - O instalador traz 22 skills com permissão total do agente: revise antes.

• README, INSTALL.md e API do GitHub de JuliusBrussee/caveman, lidos em 03/10/2026.
• Teste da JetBrains citado no README: Speaking to AI Agents like Cavemen….
• Meu teste: Windows, Node 24, 03/10/2026 (instalação da skill num projeto vazio e caveman shrink sem setup).