Binários em Plugins do Claude Code
Por Fabio Douek
Ir para seção
Explica (TLDR) como se eu fosse...
Imagina que seu ajudante robô tem um cintinho de ferramentas. Antes, você só podia dar pra ele folhinhas de livro de colorir com instruções. Agora dá pra colocar ferramentinhas de verdade no cinto, tipo um martelinho ou uma trena, e o robô pega quando precisa.
Isso abre truques novos que só instrução em papel não conseguia, e os plugins agora podem entregar gadgets prontinhos pro robô. A parte chata é que ninguém confere a caixa de ferramentas na entrada ainda. Então é bom saber de onde a ferramenta veio, do mesmo jeito que você tomaria cuidado com qualquer coisinha brilhante que um estranho oferecesse no parquinho.
Encare o diretório bin/ do Claude Code v2.1.91 como um novo fornecedor terceirizado entrando no fluxo de trabalho da equipe. As perguntas corretas de due diligence são: de onde vem o binário, qual é a cadeia de custódia do repositório, e o que a licença do plugin permite quanto a redistribuição.
O risco material: não há assinatura, verificação de hash ou targeting por arquitetura. A integridade depende do marketplace e do Git. Recomende instalar apenas de fontes auditadas, ativar disableSkillShellExecution em ambientes regulados, e registrar por escrito quem aprovou cada plugin com binário.
O quadro: equipes que precisam distribuir ferramentas compiladas junto de plugins tinham soluções paliativas frágeis, como scripts que baixavam binários em runtime. A intervenção do v2.1.91 trata exatamente esse sintoma, colocando executáveis de bin/ no PATH da Bash tool automaticamente.
A base de evidências é pequena, baseada em changelog e inspeção do binário, sem uso clínico extenso ainda. Efeitos colaterais a monitorar: ausência de sandbox em runtime, sem verificação de integridade, e possível confusão entre scripts/ e bin/. Bom candidato para quem distribui linters e formatters em Go ou Rust.
Repare no alívio que aparece quando a equipe finalmente consegue entregar um plugin autocontido, sem pedir ao usuário que instale brew, pip ou node_modules. Esse atrito desaparece, e sobra espaço mental para pensar no que o plugin realmente faz.
A ansiedade nova mora em outro lugar: saber que um binário opaco entrou no PATH pede uma conversa honesta sobre confiança. Quem no time revisa o que chega de marketplaces da comunidade? O trabalho não é só adotar bin/, é combinar com a equipe como vocês decidem em quem confiar.
Pense no bin/ como um pedal novo entrando no pedalboard. Antes, plugins só tocavam partes escritas em Markdown e JSON. Agora conseguem soltar uma linha compilada direto no groove da Bash tool, sem precisar de caminho completo.
O andamento da sessão melhora quando o plugin traz a ferramenta pronta, em vez de pedir pro músico afinar o instrumento antes de começar. Mas o pedal não tem bypass próprio: roda com as mesmas permissões do Claude, então vale escolher bem quem entra no palco antes de ligar o amp.
A história aqui é tempo até o primeiro valor. Antes do v2.1.91, autores de plugins gastavam dias amarrando scripts que baixavam binários em runtime. Agora colocam o executável em bin/ e o plugin sai autocontido, pronto para um post de lançamento curto.
O posicionamento certo não é "plugins mais poderosos", é "plugins que instalam sem pedir brew install". Ganho direto para times que distribuem linters, formatters e geradores de código em Go ou Rust. O contraponto honesto, sem assinatura nem hash, cabe no mesmo email e mostra maturidade editorial.
Visão Geral
O Claude Code v2.1.91, lançado em 2 de abril de 2026, trouxe silenciosamente uma das mudanças mais relevantes no sistema de plugins desde seu lançamento: plugins agora podem incluir executáveis nativos em um diretório bin/, e esses executáveis são automaticamente adicionados ao PATH da Bash tool.
A entrada no changelog é uma única linha:
Plugins can now ship executables under
bin/and invoke them as bare commands from the Bash tool.
Isso não faz jus ao impacto. Até então, o sistema de plugins era construído principalmente em torno de conteúdo interpretado: Markdown skills, configurações JSON, shell scripts referenciados por caminho completo. MCP servers já podiam incluir binários compilados como processo do servidor, mas esses eram opacos para a Bash tool e exigiam wrappers de protocolo MCP. Adicionar suporte nativo a bin/ muda o modelo de confiança, habilita novas categorias de plugins e aproxima o Claude Code de ecossistemas de plugins maduros como extensões do VS Code no tratamento de tooling nativo.
Este post investiga como funciona por baixo dos panos, o que a introspecção do binário v2.1.91 revela sobre a implementação, e o que isso significa para autores e usuários de plugins. Esta análise é baseada na documentação oficial, changelog e inspeção do binário v2.1.91, não em testes práticos com um plugin.
Setup
O uso na superfície é extremamente simples. A referência de plugins foi atualizada para mostrar bin/ como diretório de primeira classe no layout do plugin:
my-plugin/
├── .claude-plugin/
│ └── plugin.json
├── commands/
├── agents/
├── skills/
├── hooks/
├── bin/ # Plugin executables added to PATH
│ └── my-tool # Invokable as bare command in Bash tool
├── scripts/
├── .mcp.json
└── README.mdColoque um executável em bin/, instale o plugin, e o Claude pode invocar my-tool diretamente em qualquer chamada da Bash tool. Sem caminhos completos, sem ${CLAUDE_PLUGIN_ROOT}/bin/my-tool. Simplesmente está no PATH.
Isso é diferente do diretório scripts/ existente, que exige referências explícitas de caminho via ${CLAUDE_PLUGIN_ROOT}/scripts/process.sh e é usado principalmente por hooks e skills.
Como Funciona
Como os Binários Entram no PATH
Quando um plugin com diretório bin/ é habilitado, o Claude Code adiciona esse diretório ao PATH da Bash tool. O mecanismo está atrelado ao ciclo de vida do plugin: habilitar o plugin torna os executáveis de bin/ disponíveis, desabilitar os remove. Isso é limitado à Bash tool do Claude, não ao shell do seu sistema.
Uma nota prática: executáveis em bin/ precisam ter o bit de execução setado (chmod +x). É o mesmo requisito dos hook scripts, mas fácil de esquecer ao fazer commit de binários em um repositório Git, já que o Git só rastreia o bit de execução em sistemas Unix-like.
Considerações de Segurança
A convenção bin/ não possui verificação de integridade embutida. Se você instala um plugin de um marketplace baseado em Git, está confiando na integridade do repositório. O marketplace oficial da Anthropic é verificado, mas marketplaces da comunidade não oferecem verificação equivalente para conteúdo binário.
Algumas outras coisas que notei estarem ausentes ou não documentadas:
- Sem targeting de arquitetura: Não há distinção entre
arm64ex64. Em Macs com Apple Silicon, autores de plugins precisariam distribuir binários universais ou detectar a arquitetura por conta própria. - Sem sandboxing em runtime: Executáveis binários rodam com as mesmas permissões do Claude Code. Não há seccomp, sandbox-exec ou restrição de capabilities além do que o modo de permissão do usuário oferece.
- Sem verificação de hash: Não há validação de checksum ou assinatura para executáveis no diretório
bin/. Se um plugin distribui um binário, você está confiando na fonte.
Mitigações: disableSkillShellExecution e Similares
Distribuir o suporte a bin/ na mesma release que novos controles de segurança não foi coincidência. A v2.1.91 também introduziu a configuração disableSkillShellExecution, que desabilita execução inline de shell em skills, custom slash commands e comandos de plugin.
Skills suportam duas sintaxes para executar comandos shell durante o pré-processamento de prompts: blocos cercados (```!) e comandos inline (!`command`). Esses executam antes do prompt chegar ao Claude, injetando saída ao vivo no contexto da skill. Quando disableSkillShellExecution é true, ambas as sintaxes são substituídas por [shell command execution disabled by policy] em vez de serem executadas.
Para ser claro: essa configuração não bloqueia executáveis de bin/. Esses rodam pela Bash tool a critério do Claude, não pelo pré-processamento de skills. O que ela faz é impedir que arquivos de skill de um plugin executem comandos shell silenciosamente como efeito colateral de serem carregados. Para organizações avaliando plugins que distribuem binários, essa é a diferença entre “este plugin fornece ferramentas que o Claude pode invocar com sua aprovação” e “este plugin executa código no momento em que sua skill é ativada.”
A configuração é uma única linha em qualquer escopo de settings.json:
{
"disableSkillShellExecution": true
}Admins enterprise podem impor isso via configurações de política gerenciada, que têm precedência sobre configurações de usuário.
Isso faz parte de um conjunto mais amplo de controles enterprise distribuídos junto com bin/:
| Configuração | O que controla |
|---|---|
disableSkillShellExecution | Bloqueia shell inline em skills/commands |
disableAllHooks | Desabilita todos os hooks e execução de statusLine |
allowManagedHooksOnly | Apenas hooks implantados por admins executam |
strictPluginOnlyCustomization | Bloqueia skills, hooks, MCP ou agents que não sejam de plugins |
allowManagedMcpServersOnly | Apenas MCP servers aprovados por admins |
A combinação de disableSkillShellExecution e strictPluginOnlyCustomization dá às empresas um perímetro restrito: apenas skills de plugins verificados são carregadas, e nenhuma delas pode executar comandos shell durante o pré-processamento. Executáveis binários em bin/ ainda exigem invocação explícita da Bash tool, que é governada pelo modo de permissão do usuário.
Compatibilidade Retroativa
Isso é totalmente compatível com versões anteriores. Plugins sem diretório bin/ funcionam exatamente como antes. O schema do manifesto plugin.json não tem novos campos obrigatórios. O diretório bin/ é descoberto automaticamente por convenção, similar a como os diretórios commands/, agents/ e skills/ funcionam quando caminhos explícitos não são definidos no manifesto.
Plugins existentes que distribuem executáveis em scripts/ e os referenciam via ${CLAUDE_PLUGIN_ROOT}/scripts/... continuam funcionando. O diretório bin/ é uma adição, não uma substituição.
Comparação com Extensões do VS Code
O VS Code suporta binários nativos há anos através de pacotes de extensão específicos por plataforma. A comparação é instrutiva:
| Aspecto | VS Code | Claude Code |
|---|---|---|
| Targeting de plataforma | Flag --target com combos específicos de plataforma-arquitetura (win32-x64, darwin-arm64, linux-x64) | Sem targeting de plataforma embutido |
| Distribuição | Pacotes VSIX via marketplace | Repositórios Git ou diretórios locais |
| Assinatura | Verificação de publisher via marketplace | Sem assinatura de binários (apenas verificação do marketplace) |
| Descoberta de binários | Extension API, caminhos explícitos | Adicionado automaticamente ao PATH |
| Integração com build | Módulos Node nativos devem compilar contra a versão Node do Electron | Sem restrições de build |
A abordagem do Claude Code é significativamente mais simples: coloque um binário em bin/ e funciona. A do VS Code é mais madura, mas carrega anos de complexidade em torno de compilação de módulos Node nativos, pinning de versão do Electron e builds de matriz de plataforma.
Veredito
O recurso bin/ resolve uma limitação real. Antes da v2.1.91, plugins que precisavam de ferramentas compiladas tinham workarounds desconfortáveis: shell scripts que baixavam binários em runtime, MCP servers encapsulando ferramentas CLI presumivelmente pré-instaladas, ou instruções pedindo aos usuários para instalar dependências manualmente via brew install. Agora um plugin pode simplesmente distribuir a ferramenta.
Quem se Beneficia
Autores de plugins construindo developer tooling extraem o maior valor. Pense em linters, formatters, geradores de código e ferramentas de análise específicas de linguagem escritas em Go, Rust ou C++ que não se encaixam bem em wrappers de MCP server em Node ou Python. Um plugin poderia distribuir um único binário compilado junto com skills que o utilizam, tornando o plugin totalmente autocontido. Sem dependências pip install, sem node_modules, apenas um binário que funciona.
Quem se preocupa com segurança deve prestar atenção. Plugins em texto puro têm a vantagem de serem auditáveis. Agora que bin/ é um recurso de primeira classe, o ecossistema precisa evoluir seu modelo de confiança. Atualmente não há assinatura de binários ou verificação de hash para a convenção bin/, então você depende da verificação do marketplace e da integridade do repositório Git.
O que Eu Gostaria de Ver a Seguir
Targeting de plataforma com reconhecimento de arquitetura (arm64 vs x64) fecharia a lacuna com o VS Code. Alguma forma de atestação de binários, seja checksums, assinaturas ou ambos, fortaleceria o modelo de confiança para marketplaces da comunidade. E a documentação ainda está se atualizando: a issue #42872 no GitHub identifica várias áreas não documentadas sobre o comportamento de bin/, requisitos de empacotamento e integração com a Bash tool.
Este é um v1 do suporte a binários, e foi distribuído como uma única linha em um changelog com 12 itens. Mas é o tipo de mudança de infraestrutura que se acumula. Para meu próprio uso, já estou avaliando distribuir binários Go únicos em vez de scripts Python com cadeias frágeis de dependências. Espero que outros encontrem razões semelhantes para adotar bin/.