Semana passada um fundador de software house me mandou uma mensagem às 11h da noite, frustrado: “Thulio, toda vez que eu atualizo o Claude Code, meu plugin para de funcionar e precisa reconfigurar tudo do zero.” Já recebi variações dessa reclamação de pelo menos umas 40 das 300+ SHs que mentoro.
O problema era real e simples: plugins no Claude Code viviam no que chamamos de CLAUDE_PLUGIN_ROOT — um diretório que muda a cada atualização. Toda vez que o Anthropic lançava uma nova versão (e eles lançam várias por semana), qualquer dado que o plugin tinha guardado lá desaparecia. Configurações, dependências instaladas, caches — tudo sumia.
O Claude Code v2.1.78, lançado em 17 de março de 2026, resolveu isso de vez com uma variável nova: \${CLAUDE_PLUGIN_DATA}. E se você está construindo automações sérias para sua equipe com Claude Code, isso importa mais do que parece na primeira leitura.
O que é o CLAUDE_PLUGIN_DATA
Antes de explicar o que é novo, preciso contextualizar o que existia.
Quando você cria um plugin para o Claude Code, dois caminhos de diretório entram em jogo:
\${CLAUDE_PLUGIN_ROOT}: onde o plugin fica instalado. Scripts, arquivos de configuração, o código do plugin em si. O problema é que esse caminho muda a cada atualização do plugin. O Claude Code copia o plugin para um cache local (~/.claude/plugins/cache), e quando você atualiza para uma nova versão, esse cache muda.\${CLAUDE_PLUGIN_DATA}: o que estreou na v2.1.78. Um diretório persistente em~/.claude/plugins/data/{id}/que nunca muda. Não importa quantas vezes você atualize o plugin — esse diretório sobrevive. Só é deletado se você desinstalar o plugin completamente.
É uma distinção simples de entender mas que muda tudo na prática.
Como funciona na prática
Pensa no caso mais concreto: você criou um plugin de code review para a equipe da sua SH. Esse plugin tem um servidor MCP em Node.js com umas 50 dependências no node_modules. O que acontecia antes?
- Dev atualiza o Claude Code ou o plugin →
CLAUDE_PLUGIN_ROOTmuda - As dependências em
node_modulessomem porque estavam no diretório antigo - O hook
SessionStartprecisa reinstalar tudo do zero toda sessão - Perde 30 segundos toda vez que alguém abre o Claude Code — ou o plugin quebra
Com \${CLAUDE_PLUGIN_DATA}, o padrão recomendado pelo próprio Anthropic é este:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "diff -q \"\${CLAUDE_PLUGIN_ROOT}/package.json\" \"\${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"\${CLAUDE_PLUGIN_DATA}\" && cp \"\${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"\${CLAUDE_PLUGIN_DATA}/package.json\""
}
]
}
]
}
}Traduzindo o que esse hook faz: compara o package.json atual (no CLAUDE_PLUGIN_ROOT) com a cópia em CLAUDE_PLUGIN_DATA. Se são iguais, não faz nada. Se mudou (novo release do plugin com dependências diferentes), reinstala só as dependências novas. Se nunca foi rodado, instala pela primeira vez.
Resultado: o node_modules fica em ~/.claude/plugins/data/meu-plugin/node_modules e sobrevive a qualquer update do plugin.
E aí você pode configurar seu servidor MCP para usar essas dependências persistentes:
{
"mcpServers": {
"code-review-server": {
"command": "node",
"args": ["\${CLAUDE_PLUGIN_ROOT}/server.js"],
"env": {
"NODE_PATH": "\${CLAUDE_PLUGIN_DATA}/node_modules"
}
}
}
}O servidor MCP do seu plugin agora usa dependências persistentes. Sem reinstalar. Sem quebrar. Sem reclamação do dev às 11h da noite.
Por que isso importa para sua Software House
Na minha experiência com 300+ SHs, a maioria está usando Claude Code de duas formas: como ferramenta individual para os devs, ou tentando padronizar uso com plugins customizados para toda a equipe. É nessa segunda forma que CLAUDE_PLUGIN_DATA muda o jogo.
Impacto na produtividade: Se você tem um plugin de geração de código com padrões internos da sua SH — templates de controller, padrões de teste, convenções de naming — esse plugin provavelmente tem dependências. Antes, cada atualização do Claude Code podia quebrar o plugin silenciosamente. Agora não. O plugin fica estável independentemente de quando a Anthropic lança a próxima versão.
Impacto no custo: Imagine 15 devs na sua SH, cada um abrindo o Claude Code três vezes por dia. Se o SessionStart hook instala dependências toda vez porque o CLAUDE_PLUGIN_ROOT mudou, isso são 45 instalações desnecessárias por dia. Com CLAUDE_PLUGIN_DATA, o npm install acontece no máximo uma vez por atualização do plugin, compartilhado por todos.
Impacto na qualidade: Plugins que mantêm estado podem agora guardar coisas úteis: caches de contexto do projeto, configurações por usuário, logs de uso para você entender como o time usa a ferramenta. Antes tudo isso era perdido. Agora é persistente.
Um caso concreto: Uma das SHs que mentoro está construindo um plugin que integra o Claude Code com o sistema interno de gestão delas. Esse plugin precisa manter tokens de autenticação, preferências por projeto e histórico de operações. Com a estrutura antiga, isso teria que ficar em outro lugar (arquivo externo ao plugin, banco de dados, variável de ambiente). Com CLAUDE_PLUGIN_DATA, fica dentro do plugin mesmo, organizado, limpo.
O bônus: Plugin Agent Frontmatter
A v2.1.78 trouxe outra feature que funciona bem junto com CLAUDE_PLUGIN_DATA: Plugin Agent Frontmatter com os campos effort, maxTurns e disallowedTools.
Se você tem um agente dentro do seu plugin (um especialista de code review, por exemplo), agora pode configurar diretamente no frontmatter do arquivo Markdown do agente:
---
name: code-reviewer
description: Revisor de código especializado nos padrões da empresa
effort: medium
maxTurns: 10
disallowedTools: Write, Edit
---
Você é um revisor de código especializado nos padrões internos da empresa.
Analise o código e aponte problemas sem modificar nada.effort: medium→ controla o quanto o modelo “pensa” antes de responder (impacta custo e qualidade)maxTurns: 10→ limita o agente a 10 rodadas antes de parar (evita loops infinitos e custos descontrolados)disallowedTools: Write, Edit→ impede o agente de modificar arquivos (segurança para um reviewer read-only)
Para uma SH que distribui plugins para o time, isso é controle de custo e comportamento sem precisar tocar em código.
O que eu penso
Vou ser honesto: \${CLAUDE_PLUGIN_DATA} parece uma feature pequena. Uma variável de ambiente a mais. Mas o que ela representa é a maturação do sistema de plugins do Claude Code.
Antes, plugins eram “coisas efêmeras” — você instalava, usava, e torceu para nada mudar. Agora começam a se comportar como software de verdade: com estado persistente, com lifecycle gerenciável, com dados que sobrevivem a atualizações.
Nas 300+ SHs que acompanho, as que mais estão evoluindo em produtividade com IA são as que tratam ferramentas de IA como produtos internos, não como chatbots. Elas constroem, mantêm e evoluem seus próprios plugins. Para essas empresas, CLAUDE_PLUGIN_DATA é infraestrutura — a mesma importância de um banco de dados para um SaaS.
O mercado de software no Brasil ainda está na fase de “experimentar com IA individualmente”. As SHs que saírem na frente construindo infraestrutura de automação — plugins sérios com estado, agentes configurados, integrações com seus sistemas — vão ter uma vantagem competitiva real nos próximos anos.
Conclusão
Claude Code v2.1.78 resolveu um problema que muitos nem sabiam que tinham: plugins perdiam estado a cada atualização. \${CLAUDE_PLUGIN_DATA} cria um diretório permanente que sobrevive a qualquer update, liberando os plugins para guardar dependências, configurações e dados de forma confiável.
Se você ainda não está construindo plugins customizados para padronizar o uso do Claude Code na sua equipe, esse é um bom momento para começar. A plataforma está amadurecendo rápido, e as ferramentas para construir soluções sérias estão todas chegando.
Se você quer implementar esse nível de automação na sua software house — plugins que mantêm estado, agentes configurados para sua realidade, workflows que rodam sozinhos — é exatamente esse tipo de evolução que a gente acompanha e implementa juntos.
Sou Thulio, mentoro 300+ SHs desde 2016.
Fontes: Documentação oficial Claude Code Plugins Reference | Release v2.1.78 no GitHub
