Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 e lista quais dependências foram adicionadas no final da saída de instalação. Se uma dependência desaparecer posteriormente, /reload-plugins e a atualização automática de plugin em segundo plano a reinstalam, desde que seu marketplace já esteja em seus marketplaces configurados. Executar novamente claude plugin install no plugin dependente, ou adicionar um marketplace com claude plugin marketplace add, também resolve quaisquer dependências ausentes pendentes. Dependências de um marketplace que você não adicionou são deixadas não resolvidas. Este guia é para autores de plugins que declaram dependências em plugin.json e para mantenedores de marketplace que marcam lançamentos. 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.
Restrições de versão de dependência requerem Claude Code v2.1.110 ou posterior.

​
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. Cada entrada é um nome de plugin ou um objeto com uma restrição de versão. O manifesto a seguir declara uma dependência sem versão e uma dependência restrita:
.claude-plugin/plugin.json
{
  "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:
CampoTipoDescrição
namestringNome do plugin. Resolve dentro do mesmo marketplace que o plugin declarante. Obrigatório.
versionstringUm 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.
marketplacestringUm 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.
O campo version aceita qualquer expressão suportada pelo pacote semver do Node, incluindo intervalos de circunflexo, til, hífen e comparador. 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.

​
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:
.claude-plugin/marketplace.json
{
  "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.

​
Marque lançamentos de plugins para resolução de versão

Restrições de versão resolvem contra tags git no repositório do marketplace. Para Claude Code encontrar 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. Adicione --dry-run para ver o que seria marcado sem criar. Executar git tag secrets-vault--v2.1.0 diretamente é equivalente se você manter plugin.json e a entrada do marketplace em sincronização você mesmo. O prefixo de nome do plugin permite que um repositório de 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 plugins 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 do marketplace, filtra aquelas começando com secrets-vault--v, e busca a versão mais alta satisfazendo ~2.1.0. Se nenhuma tag correspondente existir, o plugin dependente é desabilitado com um erro listando as versões disponíveis. A semver da tag resolvida é registrada separadamente da 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 move uma tag à força para um commit diferente, a próxima instalação obtém um diretório de cache fresco em vez de reutilizar conteúdo obsoleto.
Para fontes de marketplace npm, a restrição não controla qual versão é buscada, já que a resolução baseada em tag se aplica apenas a fontes apoiadas por git. A restrição ainda é verificada no tempo de carregamento, e o plugin dependente é desabilitado com dependency-version-unsatisfied se a versão instalada não a satisfizer.

​
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 requerPlugin B requerResultado
^2.0>=2.1Uma instalação na tag 2.x mais alta em ou acima de 2.1.0. Ambos os plugins carregam.
~2.1~3.0Instalação do plugin B falha com range-conflict. Plugin A e a dependência permanecem como estavam.
=2.1.0nenhumA 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, a atualização é pulada e o pulo aparece em /doctor e 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

Ativar um plugin também ativa os plugins dos quais ele depende, e desativar um plugin é bloqueado se outro plugin ativado ainda precisar dele. Ambos os comportamentos requerem Claude Code v2.1.143 ou posterior. Versões anteriores ativam ou desativam apenas o plugin nomeado e exibem um erro dependency-unsatisfied no próximo carregamento. 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çãoResultado
Uma dependência não está instaladaAtivar 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çãoAtivar 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 destinoAtivar falha. Ative a dependência naquele escopo, ou passe --scope para escrever lá.
Todas as dependências estão instaladas e permitidasAtivar sucede e escreve true para o plugin e cada dependência que não estava já ativada no escopo de destino.
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. Isso requer Claude Code v2.1.121 ou posterior. 
claude plugin prune
Por padrão, prune opera no escopo do usuário. Use --scope project ou --scope local para direcionar um escopo diferente. Passe --dry-run para listar o que seria removido sem alterar nada. Passe -y para pular 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 -y seja passado. 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. 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, na interface /plugin, e em /doctor. O plugin afetado é desabilitado até que você resolva o erro. Os erros mais comuns e suas correções estão listados abaixo.
ErroSignificadoComo resolver
dependency-unsatisfiedUma 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-conflictOs 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-unsatisfiedA 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-tagO 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 e leia o campo errors em cada plugin.

​
Veja também