Introdução ao caveman: corte o blá-blá-blá da IA, reduza 75% dos tokens e fique mais preciso

Dificuldade de entrada | ~10 minutos | Você vai dominar o processo completo de instalação e configuração do caveman, entender os quatro modos de compressão (Lite / Full / Ultra / Wenyan) e extrair cada token da saída da IA.

Visão geral do projeto

caveman é uma habilidade de compressão da saída de um assistente de codificação por IA, desenvolvida por Julius Brussee, com o endereço no GitHub JuliusBrussee/caveman.

O foco é simples: fazer com que a resposta da IA diga apenas o que é útil. Mantendo a precisão técnica, comprime a saída em cerca de 75% dos tokens. Um estudo de 2026 (arxiv:2604.00025) até encontrou que, ao impor restrições de concisão a modelos de linguagem, em alguns benchmarks a acurácia melhora em 26 pontos percentuais — ou seja, falar muito não significa responder certo.

O caveman não é só um projeto de brincadeira. Ele já vem com quatro níveis de intensidade de compressão (Lite / Full / Ultra / Wenyan), além de três habilidades: caveman-commit (mensagens de commit ultra minimalistas), caveman-review (revisão de código em uma linha) e caveman-compress (compressão de arquivos de memória). Compatível com mais de 40 assistentes de codificação por IA, como Claude Code, Codex, Cursor, Windsurf, Cline, Copilot, Gemini CLI e outros.

Público-alvo

Você usa todo dia assistentes de codificação com IA, mas vive tropeçando em: respostas longas demais, pontos importantes pouco destacados e, no fim, você ainda precisa filtrar e extrair o essencial por conta própria. A prioridade é acelerar e reduzir custos: não quer desperdiçar tokens e tempo com rodeios sem utilidade.

Dependências e ambiente

Estrutura completa do projeto

my-project/
├── CLAUDE.md                    # Escrito depois de instalar o caveman; sempre vale (Claude Code)
├── .caveman/                    # Diretório de marcação de status (gerado automaticamente)
│   └── .caveman-active          # Modo atual: full / lite / ultra / wenyan
├── .cursor/rules/caveman.mdc    # Regra always-on do Cursor (gerada automaticamente)
├── .windsurf/rules/caveman.md   # Regra always-on do Windsurf (gerada automaticamente)
├── .clinerules/caveman.md      # Regra do Cline (gerada automaticamente)
└── .github/copilot-instructions.md  # Regra do Copilot (gerada automaticamente)

Passo a passo

Passo 1 — Instalar o caveman

O caveman suporta mais de 40 assistentes de codificação por IA. Escolha um comando conforme sua plataforma:

Claude Code (recomendado)

# Opção 1: via marketplace de plugins (o mais simples)
claude plugin marketplace add JuliusBrussee/caveman
claude plugin install caveman@caveman

# Opção 2: instalação por script (quando não há sistema de plugins)
# macOS / Linux / WSL
bash <(curl -s https://raw.githubusercontent.com/JuliusBrussee/caveman/main/hooks/install.sh)

# Windows PowerShell
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/hooks/install.ps1 | iex

Codex (VS Code + Codex)

# macOS / Linux
# 1. Clone o repositório → abra o Codex no diretório-alvo → /plugins → procure "Caveman" → Install

# Windows (precisa habilitar links simbólicos antes)
git config --global core.symlinks true
# Depois, igual ao anterior: clone → VS Code → Configurações do Codex → Plugins → instalar Caveman

Gemini CLI

gemini extensions install https://github.com/JuliusBrussee/caveman

Cursor / Windsurf / Cline / Copilot

npx skills add JuliusBrussee/caveman -a cursor
npx skills add JuliusBrussee/caveman -a windsurf
npx skills add JuliusBrussee/caveman -a cline
npx skills add JuliusBrussee/caveman -a github-copilot

Outros Agents (opencode / Roo / Goose / Kiro etc. — mais de 40)

npx skills add JuliusBrussee/caveman    # detecta automaticamente
# ou especifique
npx skills add JuliusBrussee/caveman -a opencode
npx skills add JuliusBrussee/caveman -a roo

Passo 2 — Ativar o modo caveman

Depois de instalado, em qualquer conversa basta inserir um destes comandos para ativar:

/caveman          # modo Full padrão
$caveman          # no Codex, usa-se $ em vez de /

Ou acione falando diretamente:

talk like caveman
caveman mode
less tokens please

Passo 3 — Escolher o nível de compressão

O caveman tem quatro níveis de intensidade. Para alternar, use o comando:

Comparação com o mesmo problema em React:

🗣️ Resposta normal (69 tokens):
"Your React component re-renders because you are creating a new object reference on each
render cycle. When you pass an inline object as a prop, React's shallow comparison sees
it as a different object every time, which triggers a re-render. I'd recommend using
useMemo to memoize the object."

🪶 Lite (39 tokens):
"Your component re-renders because you create a new object reference each render.
Inline object props fail shallow comparison every time. Wrap it in useMemo."

🪨 Full (19 tokens):
"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."

🔥 Ultra (15 tokens):
"Inline obj prop → new ref → re-render. useMemo."

📜 Wenyan (11 tokens):
"物出新參照，致重繪。useMemo Wrap之。"

Sair do modo caveman:

stop caveman
normal mode

Passo 4 — caveman-commit: mensagens de commit ultra minimalistas

O caveman-commit é uma habilidade dedicada a gerar mensagens de commit, seguindo Conventional Commits, e com sujeito com no máximo 50 caracteres:

/caveman-commit

Exemplo de saída:

# Commit do Claude normal (excessivamente longo):
"Added user authentication functionality including JWT token generation and validation,
password hashing with bcrypt, and session management middleware. This improves security
by implementing proper authentication flows."

# Resultado do caveman-commit:
"feat(auth): JWT + bcrypt login, session middleware"

Formato do sujeito: type(scope): subject, sempre com até 50 caracteres, why sobre what.

Passo 5 — caveman-review: revisão de código em uma linha

O caveman-review faz uma revisão linha a linha para PR ou trechos de código, com formato fixo e sem enrolação:

/caveman-review

Cole seu diff ou código; ele retorna:

L42: 🔴 bug: user null. Add guard.
L58: 🟡 perf: N+1 query. Prefetch in ORM.
L71: 🟢 nit: unused import. Remove.

Você não precisa mais ir aos comentários do PR ler um parágrafo inteiro de “Acho que aqui dá para melhorar” — ele diz diretamente em qual linha há o problema e como corrigir.

Formato: L<número-da-linha>: <🔴🟡🟢> <tipo-do-problema>: <descrição>. <sugestão-de-correção>.

Passo 6 — caveman-compress: comprimir arquivos de memória do projeto

Esta é uma das habilidades mais úteis do caveman. Seu CLAUDE.md é lido pela IA a cada sessão — então, se houver várias explicações longas e amigáveis para humanos, você desperdiça tokens toda vez apenas para ler aquilo. O caveman-compress compacta esses arquivos de memória em um formato eficiente para leitura por IA, mantendo um backup original para você editar.

/caveman:compress CLAUDE.md

Depois de rodar:

CLAUDE.md          ← versão comprimida (a que o Claude lê sempre)
CLAUDE.original.md ← backup original (você edita este; a compressão é unidirecional)

Efeito observado na prática:

Passo 7 — Configuração Always-On

Após instalar, o Claude Code / Gemini CLI ficam always-on automaticamente, sem necessidade de configuração extra.

Cursor / Windsurf / Copilot etc., ao instalar com npx skills add, precisam de um snippet extra manual para ficar sempre ativado. Escreva a intensidade que você prefere no arquivo de regras do Agent:

Seja breve como caveman. Substância técnica exata. Apenas morre o fluff.
Remova: artigos, fillers (apenas/really/basically), cortesia/cordialidades, ressalvas.
Fragmentos OK. Sinônimos curtos. Código inalterado.
Padrão: [coisa] [ação] [razão]. [próximo passo].
ATIVO A CADA RESPOSTA. Sem voltar atrás depois de muitas rodadas.
Código/commits/PRs: normal. Desligado: "stop caveman" / "normal mode".

Onde cada Agent deve ser colocado:

Passo 8 — Desinstalar / restaurar o padrão

# Desinstalar plugin no Claude Code
claude plugin uninstall caveman

# Remover hooks standalone
bash hooks/uninstall.sh           # macOS / Linux
powershell -File hooks\uninstall.ps1  # Windows

# Remover via npx skills
npx skills remove caveman

# Desinstalar no Gemini CLI
gemini extensions uninstall caveman

Após desinstalar, o diretório de status .caveman/ e os arquivos de regras precisam ser limpos manualmente (se necessário).

Solução de problemas comum

1. Plugin instalado, mas o caveman não ativa automaticamente

O Claude Code usa hook SessionStart para ativação automática. Verifique se o hook foi gravado corretamente:

# Verificar se há SessionStart no ~/.claude/settings.json
cat ~/.claude/settings.json | grep -i "SessionStart"

# Ou reinstale uma vez
claude plugin uninstall caveman
claude plugin install caveman@caveman

2. Cursor / Windsurf always-on não funciona

npx skills add não escreve automaticamente regras de always-on. Adicione manualmente o snippet do passo 7 no arquivo de regras correspondente; depois salve e recarregue o Agent.

3. Modo Wenyan sai com caracteres estranhos ou “?”

Confirme que o terminal e o editor suportam UTF-8. No Windows, a codificação padrão do PowerShell pode causar problemas:

chcp 65001
$env:LESSCHARSET=utf-8

No VS Code, confirme na barra de status (parte inferior) que a codificação de caracteres está em UTF-8.

4. caveman-compress comprimiu também blocos de código

Isso não pode acontecer — blocos de código, URLs, caminhos de arquivos e comandos são itens ignorados e não participam da compressão. Se você encontrar algo fora do esperado, normalmente é um problema de formato do arquivo (por exemplo, marcação de bloco de código ``` faltando). Nesse caso, restaure manualmente comparando com CLAUDE.original.md.

5. O comando /caveman não responde

Talvez outra skill esteja interceptando comandos com barra. No Claude Code, teste ativar por fala direta: "talk like caveman". Se ainda não funcionar, verifique se há alguma skill com o mesmo nome causando conflito.

6. Vários Agents coexistindo: caveman falha em um deles

A configuração do caveman é independente para cada Agent e não afeta os outros. Se não funcionar em um Agent específico, verifique se há arquivos relacionados ao caveman no diretório de regras desse Agent.

Leitura adicional / próximos passos

1. Avaliação em três braços do caveman: como garantir honestidade dos dados

A maioria das avaliações de “técnicas de compressão” compara a resposta da skill com a resposta normal — o que não é justo, porque terseness (conciso) por si só já melhora a qualidade. O caveman usa avaliação em três braços: _baseline_ (sem prompt do sistema), _terse_ (apenas “Answer concisely”) e <skill> (regras completas do caveman). A economia real está na diferença entre skill e terse, e não entre skill e baseline. Essa metodologia vale para qualquer avaliação de ferramentas de apoio por IA.

2. Como interpretar dados reais de benchmark

Nos testes, 10 tarefas: os tokens médios de saída caíram de 1214 para 294, economizando 65%. A faixa vai de 22% (git rebase vs merge, a explicação em si já é longa) até 87% (limites de erro do React, resposta comum fica extremamente expandida). Quanto mais fácil for “over-explaining” na tarefa, mais o caveman economiza.

3. Cavekit: ferramenta de desenvolvimento orientada a especificações do mesmo autor

JuliusBrussee/cavekit é um projeto complementar: você escreve especificações em linguagem do caveman → o Claude compila em paralelo → gera software pronto para uso. Se você usa caveman para otimizar a eficiência de saída, o cavekit pode fazer algo semelhante também no lado da entrada.

4. Criar níveis de compressão personalizados

As regras de todos os níveis de intensidade estão definidas em skills/caveman/SKILL.md. Você pode copiar uma versão, modificar a tabela de abreviações, manter a tabela ou ajustar regras de causa-efeito, e criar seus próprios níveis. Por exemplo, adicionar abreviações de termos internos do time ou proibir a substituição de certos nomes técnicos.

5. Aplicabilidade da compressão Wenyan em múltiplas línguas

A base do modo Wenyan é: a linguagem escrita mais concisa da história humana + densidade extremamente baixa de tokens por caractere. Em corpus de inglês, o wenyan-full ainda consegue comprimir algo como 40–60%, porque a gramática clássica do chinês — “omissão de sujeito + inversão verbo-objeto” — continua válida dentro de um ambiente linguístico único. É ideal para cenários que exigem compressão extrema e em que você aceita se adaptar a uma gramática específica.