SpyBara
Go Premium

plugin-dependencies.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 60 additions and 24 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Fri 25 23:58

Restringir versões de dependências de plugins

Declare restrições de versão em dependências de plugins e agrupe um conjunto de plugins curado atrás de uma única instalação.

Um plugin pode depender de outros plugins listando-os em plugin.json ou em sua entrada de marketplace. Por padrão, uma dependência rastreia a versão mais recente disponível, portanto um lançamento upstream pode alterar a dependência sob seu plugin sem aviso. Restrições de versão permitem que você mantenha uma dependência em um intervalo de versão testado até que você escolha se mover.

Quando você instala um plugin que declara dependências, Claude Code resolve e instala automaticamente, exceto por uma dependência cuja entrada de marketplace tem uma command source ou um headersHelper, que você instala primeiro. Posteriormente, /reload-plugins, atualização automática do marketplace do plugin dependente, executar novamente claude plugin install no plugin dependente e claude plugin marketplace add cada um instala qualquer dependência declarada que ainda não esteja instalada, sob as mesmas regras; se uma permanecer não resolvida, consulte Resolver erros de dependência.

Este guia é para autores de plugins que declaram dependências em plugin.json e para mantenedores de marketplace que marcam lançamentos. As dependências aqui são outros plugins; para os pacotes npm e Bun que um plugin usa, consulte Dependências de pacotes Node.js. Para instalar plugins que têm dependências, consulte Descobrir e instalar plugins. Para o esquema de manifesto completo, consulte a referência de Plugins.

Por que restringir versões de dependências

Considere um marketplace interno onde dois times publicam plugins. O time de plataforma mantém secrets-vault, um servidor MCP que envolve um backend de segredos. O time de deploy mantém deploy-kit, que chama secrets-vault para buscar credenciais durante deploys.

deploy-kit é testado contra secrets-vault v2.1.0. Sem uma restrição de versão, na próxima vez que o time de plataforma marcar um lançamento que renomeia uma ferramenta MCP, a atualização automática move secrets-vault de cada engenheiro para a nova versão e deploy-kit quebra.

Com uma restrição de versão, deploy-kit declara que precisa de secrets-vault no intervalo ~2.1.0. Engenheiros com deploy-kit instalado permanecem na versão patch 2.1.x mais alta correspondente. O time de deploy faz upgrade em seu próprio cronograma publicando uma nova versão de deploy-kit com uma restrição mais ampla.

Declare uma dependência com uma restrição de versão

Liste dependências no array dependencies do plugin.json do seu plugin.

O manifesto a seguir declara uma dependência sem versão e uma dependência restrita:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Uma entrada pode ser uma string simples com apenas o nome do plugin, como "audit-logger" no exemplo acima, que depende de qualquer versão que o marketplace desse plugin forneça. Para mais controle, use um objeto com estes campos:

Campo Tipo Descrição
name string Nome do plugin. Resolve dentro do mesmo marketplace que o plugin declarante. Obrigatório.
version string Um intervalo semver como ~2.1.0, ^2.0, >=1.4, ou =2.1.0. A dependência é buscada na versão marcada mais alta que satisfaz este intervalo.
marketplace string Um marketplace diferente para resolver name. Dependências entre marketplaces são bloqueadas a menos que o marketplace de destino esteja listado em allowCrossMarketplaceDependenciesOn no marketplace.json do marketplace raiz.

Versões pré-lançamento como 2.0.0-beta.1 são excluídas a menos que seu intervalo opte por um sufixo pré-lançamento como ^2.0.0-0.

Agrupar plugins para uma equipe

Além do name obrigatório, um manifesto de plugin pode consistir apenas em um array dependencies. Instalá-lo puxa todas as dependências, o que o torna uma forma de empacotar um conjunto de plugins curado atrás de uma única instalação.

Por exemplo, uma equipe de plataforma pode publicar bundles específicos de função em um marketplace interno para que os engenheiros executem um único claude plugin install em vez de instalar cada ferramenta separadamente:

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

Instalar backend-standard resolve e instala todas as quatro dependências.

Para adicionar uma ferramenta ao conjunto padrão posteriormente, publique uma nova versão de backend-standard com a dependência extra. A atualização automática está desativada por padrão para marketplaces não-Anthropic, portanto os engenheiros pegam a nova versão de uma de duas formas:

  • Ative a atualização automática para o marketplace em /plugin. A próxima atualização automática move o bundle para a nova versão e instala quaisquer dependências que ele adiciona.
  • Execute claude plugin update backend-standard, depois /reload-plugins para instalar as dependências recém-adicionadas.

Para distribuir bundles em toda uma organização, adicione o plugin bundle a enabledPlugins nas configurações gerenciadas.

Dependa de um plugin de outro marketplace

Por padrão, Claude Code recusa auto-instalar uma dependência que vive em um marketplace diferente do plugin que a declara. Isso evita que um marketplace puxe silenciosamente plugins de uma fonte que você não revisou.

Para permitir, o mantenedor do marketplace raiz adiciona o nome do marketplace de destino a allowCrossMarketplaceDependenciesOn em marketplace.json. O marketplace raiz é aquele que hospeda o plugin que o usuário está instalando; apenas sua lista de permissões é consultada, portanto a confiança não se encadeia através de marketplaces intermediários.

O seguinte marketplace.json permite que deploy-kit dependa de um plugin de acme-shared:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

Se o campo estiver faltando ou não incluir o marketplace de destino, a instalação falha com um erro cross-marketplace nomeando o campo a ser definido. Os usuários ainda podem instalar a dependência manualmente primeiro, o que satisfaz a restrição sem alterar a lista de permissões.

Teste um plugin e sua dependência localmente

Se você está desenvolvendo um plugin e o plugin do qual ele depende ao mesmo tempo, carregue ambos com --plugin-dir:

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

A cópia local da dependência satisfaz a entrada de dependência do seu plugin, mesmo quando a entrada nomeia um marketplace, portanto você não precisa instalar a dependência do seu marketplace. Claude Code não verifica uma restrição de versão contra uma cópia local, portanto o plugin.json local não precisa de uma version. Antes da v2.1.242, uma entrada de dependência que nomeava um marketplace nunca correspondia à cópia local, e Claude Code desabilitava seu plugin no carregamento.

Se você não instalou a dependência do seu marketplace, seu plugin para de carregar quando a cópia local desaparece:

  • Você desabilitou a cópia local: Claude Code desabilita seu plugin no próximo carregamento de plugin. Para uma entrada de dependência que nomeia um marketplace, Claude Code relata Dependency "<name>@inline" is disabled — enable it or remove the dependency; para uma entrada de nome simples, ele relata a dependência pelo seu nome simples. <name>@inline é como Claude Code identifica cada plugin --plugin-dir e --plugin-url.
  • Você iniciou uma sessão sem o sinalizador --plugin-dir da dependência: Claude Code relata a dependência como não instalada. Passe o sinalizador novamente ou instale a dependência do seu marketplace.

Lançamentos de tag de plugin para resolução de versão

Claude Code resolve restrições de versão contra tags git no repositório que hospeda a dependência: o repositório próprio do plugin para fontes de plugin github, url e git-subdir, ou o repositório do marketplace para um plugin que o marketplace referencia por um caminho relativo. Para que Claude Code encontre as versões disponíveis de uma dependência, os lançamentos do plugin upstream devem ser marcados usando uma convenção de nomenclatura específica.

Marque cada lançamento como {plugin-name}--v{version}, onde {version} corresponde ao campo version no plugin.json daquele commit. Do diretório do plugin, execute:

claude plugin tag --push

O comando claude plugin tag deriva o nome da tag do manifesto do plugin e da entrada do marketplace envolvente. Antes de criar a tag, ele valida o conteúdo do plugin, verifica se plugin.json e a entrada do marketplace concordam sobre a versão, requer uma árvore de trabalho limpa sob o diretório do plugin e recusa se a tag já existe.

  • --push envia a tag para o remote origin, portanto o repositório precisa de um remote origin configurado. Passe --remote para enviar para um diferente.
  • Se o envio falhar, a tag ainda será criada localmente e o comando sairá com um erro.
  • Com --push, uma execução bem-sucedida termina com Created tag secrets-vault--v2.1.0 e Pushed to origin, onde a última linha nomeia o remote para o qual foi enviado. Sem --push, o comando imprime o comando git push a ser executado.
  • --dry-run imprime o que seria marcado sem criá-lo.

Executar git tag secrets-vault--v2.1.0 diretamente é equivalente se você manter plugin.json e a entrada do marketplace sincronizados você mesmo.

O prefixo do nome do plugin permite que um repositório do marketplace hospede múltiplos plugins com linhas de versão independentes. O separador --v é analisado como uma correspondência de prefixo no nome completo do plugin, portanto nomes de plugin que contêm hífens são tratados corretamente.

Quando você instala um plugin que declara { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code lista as tags no repositório que hospeda secrets-vault, filtra aquelas que começam com secrets-vault--v e busca a versão mais alta que satisfaz ~2.1.0. Se nenhuma tag no repositório próprio do plugin satisfizer o intervalo, a instalação falha com Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0, que nomeia a dependência junto com seu marketplace. Para um plugin de caminho relativo sem tag correspondente, Claude Code instala a cópia atual do marketplace em vez disso e verifica a restrição quando o plugin é carregado.

Para um plugin que o marketplace referencia por um caminho relativo, um marketplace adicionado como um caminho de pasta local resolve tags da mesma forma quando a pasta é um repositório git. Isso requer Claude Code v2.1.196 ou posterior. Em dois casos Claude Code instala a dependência do conteúdo atual da pasta em vez disso:

  • Versões anteriores não leem tags de um marketplace de pasta local, portanto uma dependência restrita é carregada apenas se essa cópia satisfizer o intervalo.
  • Uma pasta local que não é um repositório git não tem tags, independentemente da versão.

O semver da tag resolvida é registrado separadamente do version do plugin.json, portanto verificações de restrição usam a tag que foi realmente buscada mesmo se plugin.json naquele commit tiver um valor obsoleto. O nome do diretório de cache para uma instalação resolvida por tag inclui um sufixo de commit-SHA de 12 caracteres, portanto se um mantenedor mover uma tag para um commit diferente, a próxima instalação obtém um diretório de cache fresco em vez de reutilizar conteúdo obsoleto.

Como restrições interagem

Quando vários plugins instalados restringem a mesma dependência, Claude Code intersecciona seus intervalos e resolve a dependência para a versão mais alta que satisfaz todos eles. A tabela abaixo mostra como combinações comuns resolvem.

Plugin A requer Plugin B requer Resultado
^2.0 >=2.1 Uma instalação na tag 2.x mais alta em ou acima de 2.1.0. Ambos os plugins carregam.
~2.1 ~3.0 Instalação do plugin B falha com range-conflict. Plugin A e a dependência permanecem como estavam.
=2.1.0 nenhum A dependência permanece em 2.1.0. Auto-update pula versões mais recentes enquanto plugin A está instalado.

Auto-update busca uma dependência restrita na tag git mais alta que satisfaz o intervalo de cada plugin instalado, em vez de na versão mais recente do marketplace, portanto a dependência continua a receber atualizações dentro de seu intervalo permitido. Se nenhuma tag satisfizer todos os intervalos, auto-update pula essa dependência e lista o pulo na aba Errors do /plugin, nomeando o plugin restringidor.

Quando você desinstala o último plugin que restringe uma dependência, a dependência não é mais mantida e retoma o rastreamento de sua entrada de marketplace na próxima atualização.

Ativar ou desativar um plugin com dependências

Esta seção aborda plugins instalados a partir de um marketplace. Para uma cópia que você carregou com --plugin-dir, consulte Testar um plugin e sua dependência localmente.

Ativar um plugin também ativa os plugins dos quais ele depende, e desativar um plugin é bloqueado se outro plugin ativado ainda precisar dele.

Quando você ativa um plugin, Claude Code também ativa suas dependências no mesmo escopo. Se uma dependência tiver suas próprias dependências, Claude Code ativa aquelas também. A mensagem de sucesso lista o que mais foi ativado junto com o plugin que você nomeou. Se uma dependência não puder ser ativada, o comando recusa e diz o que está bloqueando e como corrigir:

Condição Resultado
Uma dependência não está instalada Ativar falha e imprime o comando claude plugin install para cada dependência ausente.
Uma dependência é bloqueada pela política de plugins da sua organização Ativar falha e nomeia a dependência bloqueada.
Uma dependência está definida como false em um escopo com precedência mais alta que o escopo de destino Ativar falha. Ative a dependência naquele escopo, ou passe --scope para escrever lá.
Todas as dependências estão instaladas e permitidas Ativar sucede e escreve true para o plugin e cada dependência que não estava já ativada no escopo de destino.

Isto se aplica mesmo quando uma dependência define defaultEnabled: false em seu manifesto, porque Claude Code escreve um true explícito para ela. O mesmo se aplica na instalação: uma dependência trazida para satisfazer um plugin ativo instala com true independentemente de seu próprio padrão.

Quando você desativa um plugin, Claude Code recusa se outro plugin ativado ainda depender dele. O erro nomeia os plugins que dependem dele e dá a você um comando encadeado que os desativa na ordem correta, terminando com o que você pediu.

Por exemplo, se deploy-kit depende de secrets-vault, desativar secrets-vault sozinho falha com saída similar à seguinte:

secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

Copie o comando encadeado do erro para desativar o conjunto completo em uma etapa.

Remova dependências auto-instaladas órfãs

Dependências auto-instaladas permanecem no disco após os plugins que as instalaram serem desinstalados, no caso de você reinstalar um plugin dependente ou querer continuar usando a dependência diretamente. Para limpá-las, execute claude plugin prune para listar as dependências auto-instaladas que não têm mais nenhum plugin instalado exigindo-as e removê-las após um prompt de confirmação.

claude plugin prune

Se nada se qualificar para remoção, o comando imprime Nothing to prune com o motivo e sai. Esta é a saída esperada em uma instalação nova, não um erro.

Por padrão, prune opera no escopo do usuário e pede confirmação antes de remover qualquer coisa:

  • --scope project ou --scope local direciona um escopo diferente.
  • --dry-run lista o que seria removido sem alterar nada.
  • -y pula o prompt de confirmação. Quando stdin ou stdout não é um terminal, prune lista os órfãos e sai sem removê-los a menos que você passe -y.

Para prune como parte de uma desinstalação, passe --prune para claude plugin uninstall. Após remover o plugin nomeado, Claude Code verifica e remove quaisquer dependências auto-instaladas que agora estão órfãs. Plugins que você instalou você mesmo nunca são podados, apenas aqueles instalados automaticamente através do array dependencies de outro plugin.

O mesmo comportamento de confirmação se aplica. Quando stdin ou stdout não é um terminal, a desinstalação ainda é concluída, mas a etapa prune lista os órfãos e não remove nada a menos que você passe -y.

Por exemplo, para desinstalar deploy-kit e limpar as dependências que deixa para trás:

claude plugin uninstall deploy-kit --prune

Resolva erros de dependência

Problemas de dependência aparecem em claude plugin list e na interface /plugin, como mensagens de erro descritivas em vez dos códigos literais nesta tabela. Claude Code desabilita o plugin afetado até que você resolva o erro. A tabela abaixo lista os erros mais comuns e como resolvê-los.

Erro Significado Como resolver
dependency-unsatisfied Uma dependência declarada não está instalada, ou está instalada mas desabilitada. Execute o comando claude plugin install mostrado na mensagem de erro. Se o marketplace da dependência ainda não está configurado, adicione-o com claude plugin marketplace add e Claude Code resolve a dependência automaticamente. Se a dependência está desabilitada, ative-a.
range-conflict Os requisitos de versão para uma dependência não podem ser combinados. A mensagem de erro nomeia a causa: nenhuma versão satisfaz todos os intervalos, um intervalo não é sintaxe semver válida, ou os intervalos combinados são muito complexos para interseccionar. Desinstale ou atualize um dos plugins conflitantes, corrija qualquer string version inválida, simplifique cadeias || longas, ou peça ao autor upstream para ampliar sua restrição.
dependency-version-unsatisfied A versão da dependência instalada está fora do intervalo declarado deste plugin. Execute claude plugin install <dependency>@<marketplace> para re-resolver a dependência contra todas as restrições atuais.
no-matching-tag O repositório da dependência não tem uma tag {name}--v* satisfazendo o intervalo. Verifique se o upstream marcou lançamentos usando a convenção acima, ou relaxe seu intervalo.

Para verificar esses erros programaticamente, execute claude plugin list --json. Plugins com problemas incluem um campo errors listando-os. Plugins que carregaram corretamente omitem o campo.

Veja também