Binários em Plugins do Claude Code

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.md

Coloque 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 arm64 e x64. 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/.