🪨 Caverna — Modo Ultra-Comprimido PT-BR para Claude Code

Fork 100% em português do caveman (Julius Brussee) Profissionalizado, com regras invioláveis de acentuação, emojis preservados e safety carve-out expandido. "Pra que usar muitos token se poucos resolve?" — mas em PT-BR, com acento, e sem perder a alma brasileira.

---

🎯 O que é

Caverna é um plugin para Claude Code que comprime as respostas do modelo em ~70-80% mantendo toda a precisão técnica. Ele droppa artigos, filler, pleasantries e hedging — mas preserva código, acentos, emojis e vocabulário técnico.

Antes e depois

	Resposta Normal	Resposta Caverna Ultra
Prompt	"Por que componente React re-renderiza?"	(mesmo)
Saída	"O componente re-renderiza porque você está criando uma nova referência de objeto a cada render. Para resolver, envolva em useMemo."	"Ref nova → re-render. useMemo."
Tokens	~72	~13
Compressão	0%	82%

---

🇧🇷 O que é diferente do caveman original

O caveman do @JuliusBrussee é brilhante — corta tokens como nenhum outro plugin. Mas ele é 100% em inglês, e dev brasileiro que força PT-BR perdia o benefício. A gente pegou todo o trabalho dele, trouxe pro modo brasileiro, e profissionalizou em 10 pontos críticos:

#	Melhoria	Caveman EN	Caverna PT-BR
1	Idioma	Inglês only	🇧🇷 PT-BR nativo
2	Acentos	N/A	✅ Invioláveis (á/é/ç/ã/ô/ó/ú/í/ü)
3	Emojis	❌ Dropa em Ultra	✅ Preservados (densidade informacional)
4	Safety carve-out	4 categorias	🛡️ Expandido — Supabase destructive, deploy prod, migrations, decisões arquiteturais
5	Vocabulário preservado	Nomes próprios genéricos	📚 Glossário dedicado — termos técnicos, stack, siglas BR
6	Bilíngue técnico	Monolíngue	🇺🇸 EN permitido em termos consagrados (useMemo, async, middleware, RLS)
7	Modo padrão	full	⚡ Ultra travado (máxima compressão por default)
8	Escopo de instalação	Global (~/.claude)	🏠 Local ao projeto suportado (não vaza entre workspaces)
9	Documentação	README + CLAUDE.md	📖 BENCHMARK medido + GLOSSARIO + COEXISTENCIA
10	Integração com ecossistema	Standalone	🤝 Coexiste com token-efficiency rules (cache + routing)

---

📊 Benchmark

5 prompts representativos medidos (ver docs/BENCHMARK.md):

Prompt	Baseline	Ultra	Compressão	Acentos
N+1 Prisma	72 palavras	13	82%	✅
useMemo vs useCallback	53	15	72%	✅
Deploy sem auth (safety)	verbose	verbose	0% (esperado — safety dispara)	✅
n8n 401	58	17	71%	✅
Commit XSS (caverna-commit)	formato conv.	formato conv.	N/A	✅

Média de compressão em Ultra: 75% Acentos preservados: 100% Safety carve-out funcionou em prompt destrutivo: ✅

---

🚀 Instalação

Opção 1 — Plugin nativo Claude Code (recomendado)

claude plugin marketplace add deivithi/caverna && claude plugin install caverna@caverna

Opção 2 — Standalone (Windows)

irm https://raw.githubusercontent.com/deivithi/caverna/main/hooks/install.ps1 | iex

Opção 3 — Standalone (macOS/Linux)

bash <(curl -s https://raw.githubusercontent.com/deivithi/caverna/main/hooks/install.sh)

Opção 4 — Local ao projeto

git clone https://github.com/deivithi/caverna .claude/
# Copia skills/, hooks/, commands/, rules/, docs/ para .claude/ do seu projeto
# Adiciona hooks + statusLine no .claude/settings.local.json (ver hooks/install.ps1)

---

🎛️ Modos

Modo	Trigger	Efeito
leve	/caverna leve	Sem filler/hedging. Mantém artigos + frases completas.
completo	/caverna completo	Dropa artigos, fragmentos OK, sinônimos curtos.
ultra ⚡	/caverna ultra (padrão)	Abrevia (BD/aut/config/req/res/fn/impl), setas → p/ causalidade, 1 palavra quando basta.
off	/caverna off	Desativa na sessão atual.

Desativação natural

Funciona sem slash command: diga "para caverna", "desliga caverna" ou "modo normal".

---

🛠️ Skills incluídas

Skill	Trigger	Uso
caverna	/caverna	Modo compressão geral
caverna-commit	/caverna-commit	Commit messages Conventional PT-BR (subject ≤50 chars)
caverna-review	/caverna-review	Code review formato L42: 🔴 bug: user null. Adiciona guard.
caverna-compress	/caverna-compress <arquivo>	Comprime .md preservando código + acentos + estrutura
caverna-help	/caverna-help	Card de referência rápida

---

🛡️ Safety Carve-Outs (Expandido vs original)

Caverna pausa automaticamente e responde verbose para:

Categoria A — Herdado do caveman

• Avisos de segurança (senhas, tokens, secrets)
• Ação irreversível (DROP TABLE, rm -rf, git push --force)
• Sequência multi-passo crítica
• Usuário confuso ou repete pergunta

Categoria B — Expandido no fork PT-BR

• Supabase destructive — DROP, TRUNCATE, DELETE sem WHERE, rm em migrations/
• Deploy production — vercel --prod, supabase db push, cloudflare deploy, git push --force main
• Migrations / schema changes — qualquer .sql em migrations/, ALTER POLICY, edge function deploy com impacto em dados
• Checklist pré-entrega — enumerar itens completos, nunca Ultra
• Decisões arquiteturais — "pensar > agir"

Ver skills/caverna/references/safety-carveouts.md.

---

📚 Estrutura do repo

caverna/
├── .claude-plugin/           # Manifesto de plugin nativo Claude Code
│   ├── plugin.json
│   └── marketplace.json
├── skills/                   # 5 skills PT-BR
│   ├── caverna/
│   │   ├── SKILL.md          # Regras core
│   │   ├── gotchas.md        # Armadilhas conhecidas
│   │   └── references/
│   │       ├── compressoes.md       # Tabela completa PT-BR → Ultra
│   │       └── safety-carveouts.md
│   ├── caverna-commit/SKILL.md
│   ├── caverna-review/SKILL.md
│   ├── caverna-help/SKILL.md
│   └── caverna-compress/SKILL.md
├── hooks/                    # Hooks Node.js
│   ├── caverna-activate.js   # SessionStart — injeta regras
│   ├── caverna-mode-tracker.js  # UserPromptSubmit — detecta /caverna + linguagem natural
│   ├── caverna-config.js     # Resolver (env var, config file, default='ultra')
│   ├── caverna-statusline.ps1   # Windows badge
│   ├── caverna-statusline.sh    # macOS/Linux badge
│   ├── install.ps1           # Instalador Windows
│   ├── install.sh            # Instalador macOS/Linux
│   └── package.json          # CommonJS marker
├── commands/                 # 5 slash commands
│   ├── caverna.md
│   ├── caverna-commit.md
│   ├── caverna-review.md
│   ├── caverna-compress.md
│   └── caverna-help.md
├── rules/                    # Rule de ativação
│   └── caverna-activate.md
├── docs/                     # Documentação expandida
│   ├── BENCHMARK.md          # 5 prompts reais medidos
│   ├── GLOSSARIO.md          # Vocabulário preservado (pt-BR + siglas)
│   └── COEXISTENCIA.md       # Mapa vs token-efficiency rules
├── LICENSE                   # MIT (herdado do caveman)
├── CHANGELOG.md              # Histórico de versões
└── README.md                 # Este arquivo

---

⚙️ Configuração

Padrão: ultra

Resolução em ordem de prioridade:

1. Variável de ambiente CAVERNA_DEFAULT_MODE
2. Arquivo config (~/.config/caverna/config.json ou %APPDATA%\caverna\config.json)
3. Default: ultra (fork PT-BR) / full (original)

Exemplo — trocar padrão para completo:

export CAVERNA_DEFAULT_MODE=completo

Ou em ~/.config/caverna/config.json:

{ "defaultMode": "completo" }

Desativar auto-ativação

export CAVERNA_DEFAULT_MODE=off

Caverna não ativa no SessionStart. Ativa manualmente com /caverna.

---

🧪 Exemplos Ultra PT-BR

"Como otimizar query N+1 em Prisma?"

Normal:

Para otimizar uma query N+1 no Prisma, você precisa usar include ou select na sua chamada de busca. Isso permite que o Prisma faça um JOIN SQL único em vez de múltiplas queries separadas.

Ultra:

N+1 Prisma → include: { author: true } no findMany. JOIN único, não N queries.

"Diferença entre useMemo e useCallback?"

Normal:

A principal diferença é que useMemo memoiza um valor computado, enquanto useCallback memoiza uma função. Ambos são hooks do React que só recalculam o resultado quando as dependências no array de deps mudam.

Ultra:

useMemo = valor. useCallback = fn. Deps mudou → recalcula. Caro: useMemo. Prop p/ filho memo: useCallback.

"Por que n8n workflow retorna 401?"

Normal:

Um workflow n8n retornando 401 geralmente indica que o webhook de entrada está protegido por autenticação e o header ou token não foi enviado corretamente.

Ultra:

401 n8n → webhook c/ aut ativo s/ header correto. OU OAuth2 expirada node downstream. Checa config webhook + logs execução.

---

🤝 Coexiste com outras rules

Caverna não substitui rules de cache/routing/thinking — ela complementa. Juntas:

• Token Efficiency (cache, routing, thinking) → economia no INPUT
• Caverna → compressão no OUTPUT

Economia combinada em sessão real:

• Baseline: ~869 tokens
• Só cache: ~149 tokens (83% off)
• Cache + Caverna Ultra: ~95 tokens (89% off)

Ver docs/COEXISTENCIA.md.

---

🙏 Créditos

Este projeto é um fork direto do caveman criado por Julius Brussee. Toda a arquitetura de hooks, o conceito de modos de intensidade, a estrutura de safety carve-out, e a engenharia de flag file symlink-safe vêm do trabalho dele.

O que a gente fez:

• Traduziu 100% das skills e hooks para PT-BR com profissionalização
• Adicionou regras invioláveis de acentuação (á/é/ç/ã) — crítico p/ mercado BR
• Preservou emojis como informação densa (vs caveman que dropa)
• Expandiu safety carve-out com stack-specific rules (Supabase, deploy, migrations)
• Criou glossário de vocabulário brasileiro e termos técnicos preservados
• Documentou coexistência com outras rules de token efficiency
• Benchmark medido em prompts reais (não só teóricos)

Licença: MIT (igual original). Créditos duplos no LICENSE.

---

📬 Contribuir

Issues e PRs bem-vindos. Para novos idiomas além de PT-BR, abra uma issue primeiro — a arquitetura suporta múltiplos locales via env var.

---

📖 Ver também

• Caveman original (EN) — origem do projeto
• Claude Code docs — Plugins
• Claude Code docs — Hooks

---

🪨 Caverna — pra que usar muitos token se poucos resolve?