Passer au contenu principal
Utilisez cette page quand un plugin ne s’est pas chargé, a chargé une copie différente de celle attendue, ou n’a pas appliqué une mise à jour, et vous voulez voir quelle source, portée de paramètres, ou fichier sur disque a décidé cela. Elle donne les règles que Claude Code applique au démarrage d’une session et chaque fois que vous exécutez /reload-plugins. Vous pouvez aussi demander à Claude de lire cette page et diagnostiquer votre configuration.
Ces cas sont couverts sur d’autres pages :
Commencez par Vérifier à quel stade un plugin est arrivé pour les trois stades qu’un plugin installé traverse, ou allez à la section qui correspond à ce que vous voyez :

​
Vérifier à quel stade un plugin est arrivé

Une entrée enabledPlugins devient un plugin que vous pouvez utiliser en stades : vos paramètres le déclarent, Claude Code le récupère sur disque, et la session en cours le charge. Quand un plugin ne se comporte pas comme un fichier de paramètres le suggère, vérifiez à quel stade il est arrivé :
  • Déclaré, dans les paramètres : enabledPlugins dit quels plugins doivent être activés, et extraKnownMarketplaces dit quels marchés doivent exister. Quand vous exécutez claude plugin marketplace add, Claude Code écrit le marché dans extraKnownMarketplaces dans vos paramètres utilisateur ainsi que sur disque
  • Récupéré, sur disque sous ~/.claude/plugins/ : les enregistrements de ce que Claude Code a récupéré, et les fichiers récupérés eux-mêmes :
    • known_marketplaces.json enregistre chaque marché que Claude Code a récupéré, avec sa source, installLocation, lastUpdated, et autoUpdate. Il y a un known_marketplaces.json par utilisateur, donc un marché que vous ajoutez dans un projet est disponible dans chaque projet
    • installed_plugins.json enregistre chaque installation avec sa scope, installPath, et version
    • cache/ contient les fichiers du plugin
  • Chargé, dans la session en cours : l’ensemble de plugins que Claude Code a chargé au démarrage ou au dernier /reload-plugins. Les modifications des paramètres ou du disque ne atteignent cette couche que quand vous exécutez /reload-plugins ou démarrez une nouvelle session. C’est pourquoi claude plugin update se termine par Restart to apply changes. et les mises à jour en arrière-plan vous invitent avec Run /reload-plugins to apply

​
Plugins et marchés qui ne sont pas sur disque au démarrage de la session

Les plugins se chargent au démarrage de la session à partir de installed_plugins.json et du cache sans utiliser le réseau. Après le démarrage de la session, Claude Code vérifie les marchés déclarés en arrière-plan :
  • Un marché que les paramètres déclarent mais que known_marketplaces.json manque : Claude Code le clone, puis recharge les plugins et télécharge les plugins activés qui ne sont pas en cache
  • Un marché déclaré dont la source a changé dans les paramètres : Claude Code le récupère à nouveau à partir de la nouvelle source et affiche Plugins changed. Run /reload-plugins to activate.
Un plugin activé qu’aucun de ces deux chemins n’a récupéré et qui n’a pas de répertoire de cache utilisable affiche Plugin "<name>" not cached at <path> dans l’onglet Errors de /plugin. Pour le correctif, voir Plugin "<name>" not cached at <path>.

​
Trouver d’où vient un plugin

Chaque plugin a un id de la forme <name>@<origin>, ce que vous voyez dans les fichiers de paramètres et dans claude plugin list --json. La partie après @ vous dit où Claude Code a trouvé le plugin : Pour un plugin de marché, <name> est le nom d’entrée dans marketplace.json ; pour @inline et @skills-dir c’est le name dans le manifeste du plugin. Les noms d’origine dans ce tableau sont réservés, donc aucun marché ne peut être nommé inline, skills-dir, ou synced.

​
Nom d’entrée et nom de manifeste

Un plugin de marché a deux noms, et ils peuvent différer :
  • Le nom d’entrée dans marketplace.json : la clé d’installation et d’activation. C’est ce que vous écrivez dans enabledPlugins, ce que le répertoire de cache est nommé d’après, et ce que claude plugin list affiche
  • Le name dans le manifeste : ce sous lequel les composants du plugin sont espacés de noms, et ce que les conflits de noms comparent

​
Plugins partagés via un référentiel

Pour partager un plugin via un référentiel, listez-le sous enabledPlugins dans .claude/settings.json ou placez-le sous .claude/skills/. Claude Code ne scanne pas le répertoire .claude/plugins/ d’un projet. Une session cloud n’ajoute pas les marchés qu’un référentiel liste sous extraKnownMarketplaces, car cela nécessite la boîte de dialogue de confiance de l’espace de travail, qu’une session cloud ne montre jamais.

​
Vérification de confiance et limites des composants pour les plugins de dépôt

Un plugin de portée de projet est archivé dans le référentiel et atteint chaque collaborateur qui le clone. Parce que ce contenu provient du référentiel plutôt que de vous, il se charge seulement après la même vérification de confiance qui s’applique aux règles d’autorisation de projet dans .claude/settings.json. Faire confiance à un dossier parent ou exécuter avec -p ne suffit pas. Les composants qui exécutent du code sont restreints davantage :
  • Les serveurs MCP qu’il déclare passent par l’approbation par serveur identique qu’un .mcp.json de projet
  • Les serveurs MCP qu’il déclare comme un bundle MCP, un fichier .mcpb ou .dxt, ou à partir d’un fichier en dehors du répertoire du plugin sont ignorés. Déclarez-les en ligne ou dans un .mcp.json à l’intérieur du répertoire du plugin
  • Les moniteurs en arrière-plan ne se chargent pas
Ni la vérification de confiance ni ces limites de composants ne s’appliquent à un plugin situé sous votre propre ~/.claude/skills/. Pour savoir comment écrire des plugins --plugin-dir et de répertoire de compétences, voir Créer des plugins.

​
Vérifier pourquoi un plugin de dépôt ne s’est pas chargé

Si un plugin dans le .claude/skills/ de votre dépôt ne se charge pas, vérifiez ces causes :

​
Plugins de répertoire de skills bloqués par les paramètres gérés

Si un dossier de plugin dans ~/.claude/skills/ ou dans le .claude/skills/ d’un projet ne s’est pas chargé et que vous ne voyez aucune erreur, votre administrateur l’a peut-être bloqué via les paramètres gérés. Ces dossiers proviennent de vous ou de votre dépôt plutôt que d’une marketplace, donc Claude Code les ignore lorsque votre administrateur définit l’une de ces restrictions :
  • Personnalisation verrouillée sur les plugins : strictPluginOnlyCustomization défini à true ou à un tableau nommant un ou plusieurs types de personnalisation à verrouiller. Le plugin entier est ignoré dès qu’un seul type est verrouillé, comme mcp, quels que soient les composants qu’il contient.
  • Sources de marketplace restreintes : une liste d’autorisation strictKnownMarketplaces sans entrée { "source": "skills-dir" }, ou une liste blockedMarketplaces qui en contient une.
/plugin et claude plugin list n’affichent ni plugin ni erreur pour un dossier ignoré. Ses commandes /<name>:<skill> et ses agents sont absents, tout comme ses hooks et ses serveurs MCP. Sauf si les skills font partie des types verrouillés, un SKILL.md à la racine du dossier se charge quand même comme un skill ordinaire. Dans ce cas, /<name> continue de fonctionner, et l’onglet Installed de /plugin liste ce skill sous Skills.
  • Confirmer la cause : exécutez /status dans une session Claude Code. Si la ligne Setting sources liste Enterprise managed settings, demandez à votre administrateur si l’un de ces paramètres s’applique à vous. Si ce n’est pas le cas, voir Vérifier pourquoi un plugin de dépôt ne s’est pas chargé pour d’autres causes.
  • Charger le plugin entier : ajoutez-le à une marketplace autorisée par votre organisation et installez-le à partir de celle-ci. Pour le charger plutôt pour une seule session, démarrez claude depuis votre shell avec --plugin-dir et le chemin du dossier, ce qui fonctionne sauf si votre administrateur a également désactivé ce flag.

​
Plugins synchronisés à partir de claude.ai

Un plugin que vous activez pour votre compte claude.ai se charge aussi dans Claude Code, aux côtés des plugins que vous installez à partir de marchés. Cela inclut les plugins que votre organisation active pour ses membres. Chacun de ces plugins se charge comme <name>@synced, sans marché et sans enregistrement d’installation. Dans les sessions de terminal, les compétences, agents, hooks, serveurs MCP et serveurs LSP d’un plugin synchronisé se chargent tous, avec la même confiance qu’un plugin de marché que vous avez installé. Pour les composants que Cowork charge, voir le tableau de comparaison du support des composants sur claude.com. Les plugins synchronisés se chargent dans les sessions Cowork et dans les sessions de terminal où vous vous connectez avec votre compte claude.ai :
  • Cowork : Claude Code les télécharge dans l’environnement propre de la session au démarrage de la session
  • Sessions de terminal : chaque fois que vous démarrez Claude Code, il se synchronise une fois en arrière-plan, téléchargeant les plugins nouveaux et mis à jour et supprimant ceux que vous ou votre organisation avez désactivés. La synchronisation dans les sessions de terminal nécessite Claude Code v2.1.273 ou ultérieur

​
Timing de synchronisation dans les sessions Cowork cloud

Si vous activez ou désactivez un plugin pour votre compte claude.ai pendant une session Cowork qui s’exécute dans le cloud, continuez à travailler dans cette session. Si rien n’a changé après quelques messages, démarrez une nouvelle session.

​
Timing de synchronisation dans les sessions de terminal

Parce que la synchronisation de terminal s’exécute en arrière-plan, elle peut se terminer après le démarrage de votre session. Quand elle ajoute, met à jour ou supprime un plugin synchronisé dans une session interactive, vous voyez Plugins changed. Run /reload-plugins to activate. Exécutez /reload-plugins pour charger la modification dans cette session, ou laissez-la pour la prochaine fois que vous démarrez Claude Code. Si vous activez ou désactivez un plugin pour votre compte claude.ai pendant une session de terminal, Claude Code le télécharge ou le supprime la prochaine fois que vous démarrez Claude Code.

​
Exigences de connexion pour la synchronisation de terminal

Dans votre terminal, les plugins se synchronisent uniquement dans les sessions où vous vous connectez avec votre compte claude.ai. Claude Code ne télécharge ni ne charge les plugins synchronisés dans ces sessions de terminal, même après vous être connecté avec /login : Si vous vous êtes connecté sur une version antérieure de Claude Code, cette connexion ne couvre pas les plugins jusqu’à ce que Claude Code la renouvelle en arrière-plan. Pour accéder plus tôt, exécutez /login à nouveau. La synchronisation des plugins commence alors la prochaine fois que vous démarrez Claude Code.

​
Contrôler quels plugins synchronisés se chargent

Vous pouvez désactiver les plugins synchronisés un par un, sauf un plugin que votre organisation exige, ou désactiver tous les plugins synchronisés sur la machine :
  • Un plugin : claude plugin disable <name>@synced dans votre shell et l’onglet Installed de /plugin dans une session enregistrent tous les deux "<name>@synced": false dans votre enabledPlugins au niveau utilisateur. Pour garder le plugin hors d’un projet dans chaque environnement, définissez la même clé dans le .claude/settings.json engagé du projet
  • Tous les plugins synchronisés sur une machine : définissez syncClaudeAiPlugins à false dans vos paramètres utilisateur, ou votre organisation le définit dans les paramètres gérés. Claude Code arrête de télécharger, et la prochaine fois que vous le démarrez, il déplace les plugins qu’il a déjà synchronisés vers ~/.claude/plugins/.trash/ et ne les charge plus. Si votre organisation désactive les Compétences sur claude.ai, les plugins arrêtent aussi de se synchroniser
  • Un plugin que votre organisation exige : un plugin que votre organisation marque comme requis sur claude.ai se charge même si vous l’avez désactivé plus tôt. claude plugin disable le refuse avec Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it., et claude plugin list le marque required by your org
Pour supprimer un plugin sur claude.ai, voir Gérer les plugins installés.

​
Trouver où un plugin est activé

Vous pouvez définir une entrée enabledPlugins dans l’une de six sources. Le tableau les liste de la plus basse à la plus haute précédence, et qui chacune s’applique. Pour les fichiers de paramètres eux-mêmes, voir Fichiers de paramètres et qui ils affectent. Ces sources fusionnent clé par clé. Pour chaque id de plugin, la valeur qui s’applique est celle de la source de plus haute précédence qui mentionne l’id. Une source qui ne mentionne pas l’id laisse la valeur de la source de plus basse précédence en effet.

​
Désactivé dans les paramètres utilisateur mais se charge toujours

Si vous définissez un plugin à false dans ~/.claude/settings.json et qu’il se charge toujours, un true dans une source de plus haute précédence le remplace. La ligne du plugin dans claude plugin list et dans /plugin affiche Disabled in ~/.claude/settings.json but still loads — project settings enable it, which overrides your user setting. Le message nomme la source qui vous a remplacé : project, project, gitignored pour .claude/settings.local.json, cli flag, ou managed. Pour refuser un plugin activé par le projet sur votre machine, définissez l’id à false dans .claude/settings.local.json, qui a une plus haute précédence que le fichier de projet.

​
Activé dans les paramètres de projet mais non installé

Quand le seul true d’un plugin est dans le .claude/settings.json du projet, Claude Code ne le récupère pas sur une machine où il n’est pas installé, sauf si son entrée de marché a une source de chemin relatif ou un répertoire de semence le contient déjà. À la place, l’onglet Errors de /plugin affiche Plugin "<name>" is enabled in project settings but isn't installed here. Un plugin de chemin relatif n’a besoin d’aucun enregistrement d’installation car il se charge à partir du marché lui-même. Claude Code récupère un plugin avec une source externe uniquement quand l’une de ces sources le définit à true :
  • Vos paramètres utilisateur
  • Un .claude/settings.local.json que git ne suit pas
  • L’indicateur --settings
  • Paramètres gérés

​
Trouver les plugins sur disque

Claude Code garde les fichiers de plugin et les enregistrements d’état sous une racine de plugins, qui est ~/.claude/plugins sauf si vous définissez CLAUDE_CODE_PLUGIN_CACHE_DIR. Chaque chemin du tableau est relatif à cette racine. Parce que ${CLAUDE_PLUGIN_ROOT} pointe vers un répertoire de version, le chemin racine d’un plugin change avec chaque version. Gardez les fichiers durables d’un plugin dans ${CLAUDE_PLUGIN_DATA} à la place.

​
Plugins en place et copiés

Claude Code charge certains plugins en place d’où vous les gardez et copie le reste dans le cache, selon leur origine :
  • Plugins --plugin-dir et de répertoire de compétences : le répertoire se charge en place et n’est jamais copié. Une archive --plugin-url ou un .zip --plugin-dir est d’abord extrait dans un répertoire temporaire de session
  • Plugins de chemin relatif dans une marketplace que vous avez ajoutée à partir d’un chemin local : le plugin se charge en place à partir de son chemin à l’intérieur du dossier de la marketplace. Vos modifications du répertoire source prennent effet au prochain démarrage de session ou /reload-plugins, et vous n’avez pas besoin d’augmenter la version. Les processus de hook du plugin et les serveurs MCP et LSP reçoivent un CLAUDE_PLUGIN_ROOT qui pointe vers le répertoire source. Pour ses dépendances de package Node.js, voir Quand l’installation de dépendance s’exécute
  • Plugins de source command en mode lien : le répertoire que la commande a imprimé se charge en place, via des liens dans l’entrée de cache
  • Tous les autres plugins de marché : Claude Code copie le plugin dans cache/<marketplace>/<plugin>/<version>/ à l’installation et charge cette copie. Les fichiers en dehors du répertoire du plugin ne sont pas copiés, donc quand un script à l’intérieur d’un plugin copié lit un chemin au-dessus de la racine du plugin, comme ../shared, il ne les trouve pas

​
Chemins qui s’échappent du répertoire du plugin

Qu’un plugin se charge en place ou à partir d’une copie en cache, Claude Code ne le laisse pas déclarer des composants en dehors de son propre répertoire. Il rejette un chemin de composant qui se résout en dehors de la racine du plugin, que le chemin soit déclaré dans plugin.json ou dans une entrée de marché :
  • Un chemin qui pointe en dehors du plugin tel qu’écrit, comme ../shared-utils
  • Un lien symbolique qui mène en dehors du plugin, autre que les liens entre plugins dans un marché
  • Sur macOS et Linux, un chemin qui contient une barre oblique inverse n’importe où dedans, même quand le chemin reste à l’intérieur du plugin. Les composants déclarés avec des chemins de barre oblique inverse se chargent donc sur Windows uniquement, donc écrivez les chemins de composant avec des barres obliques avant, comme ./commands/deploy.md
Un chemin rejeté apparaît comme une erreur path escapes plugin directory, et le plugin se charge sans ce composant.

​
Nettoyage des versions précédentes

Quand vous mettez à jour ou désinstallez un plugin, Claude Code écrit un marqueur .orphaned_at dans le répertoire de version précédente. Il supprime ce répertoire dans un nettoyage en arrière-plan 14 jours plus tard, donc une session qui a déjà chargé l’ancienne version continue de s’exécuter. Le balayage s’exécute uniquement tant que installed_plugins.json enregistre au moins une installation. Après que vous ayez désinstallé votre dernier plugin, les répertoires orphelins restent jusqu’à ce que vous en installiez un autre.

​
Dépendances de package Node.js

Quand Claude Code copie un plugin dans le cache, il installe aussi les dépendances de package Node.js du plugin là, donc les hooks et serveurs MCP du plugin peuvent les charger. Cette section couvre les packages npm et Bun qu’un plugin déclare dans son propre package.json. Pour les plugins qui dépendent d’autres plugins, voir versions de dépendance de plugin.

​
Quand l’installation de dépendance s’exécute

Claude Code installe les dépendances dans le répertoire de version copié chaque fois qu’il en crée un :
  • Quand vous installez un plugin
  • Quand Claude Code met à jour un plugin vers une nouvelle version
  • Au démarrage de la session quand un plugin activé n’est pas en cache, comme sur une nouvelle machine
Pour un plugin de chemin relatif chargé en place à partir d’une marketplace que vous avez ajoutée à partir d’un chemin local, Claude Code n’installe pas les dépendances dans le répertoire source. Installez-les là vous-même, ou à partir d’un hook dans ${CLAUDE_PLUGIN_DATA}. L’installation s’exécute uniquement quand le répertoire racine du plugin contient à la fois un package.json et un fichier de verrouillage pris en charge. Le fichier de verrouillage décide quel gestionnaire de packages Claude Code exécute : Si un plugin contient plus d’un de ces fichiers de verrouillage, Claude Code utilise la première correspondance, en vérifiant dans l’ordre : bun.lock, npm-shrinkwrap.json, package-lock.json. Claude Code ignore l’installation dans ces cas de fichier de verrouillage :
  • bun.lockb : le fichier de verrouillage binaire de Bun ne peut pas être vérifié. Fournissez plutôt un bun.lock texte ou un fichier de verrouillage npm
  • yarn.lock ou pnpm-lock.yaml : remplacez-le par un fichier de verrouillage npm
  • Un fichier de verrouillage dans un format que Claude Code ne lit pas : un fichier de verrouillage npm nécessite un lockfileVersion de 2 ou 3, qu’écrit npm 7 ou ultérieur, et un bun.lock nécessite un lockfileVersion ne dépassant pas 2
Incluez un fichier de verrouillage npm pour atteindre le plus d’utilisateurs. Claude Code exécute le gestionnaire de packages du fichier de verrouillage correspondant à partir du PATH de l’utilisateur et n’essaie pas l’autre fichier de verrouillage à la place si ce gestionnaire de packages manque. Pour un plugin distribué via une source npm, utilisez npm-shrinkwrap.json, car npm exclut package-lock.json des packages publiés.

​
Limites sur l’installation de dépendance

Claude Code contraint cette installation de dépendance de sorte qu’aucun code du plugin ou de ses packages ne s’exécute pendant celle-ci, et limite combien de temps elle peut s’exécuter :
  • Packages de registre uniquement : chaque dépendance doit être un package de registre épinglé dans le fichier de verrouillage à une version exacte. Un plugin avec une dépendance git, GitHub, de dossier, d’espace de travail ou liée n’obtient aucune installation.
  • Téléchargements https : un lien de téléchargement dans le fichier de verrouillage doit utiliser https, sauf s’il pointe vers le registre npm par défaut de l’utilisateur qui effectue l’installation.
  • Un dossier d’installation séparé : le gestionnaire de packages s’exécute dans un dossier qui lui est propre et qui ne contient qu’une copie de la liste de dépendances vérifiée, de sorte que npm et Bun ne lisent pas le .npmrc, le .env ou le bunfig.toml du plugin. Quand l’installation réussit, Claude Code déplace le node_modules résultant dans le plugin.
  • Résolution gelée : l’installation utilise exactement les versions que le fichier de verrouillage épingle, et Claude Code l’ignore quand package.json et le fichier de verrouillage ne listent pas les mêmes dépendances
  • Pas de scripts de cycle de vie : --ignore-scripts empêche les scripts preinstall, install, et postinstall de s’exécuter, donc les dépendances qui construisent des modules natifs dans ces scripts téléchargent mais ne compilent pas pendant cette installation
  • Pas de remplacements ni de correctifs : un plugin dont le package.json définit des overrides npm n’obtient aucune installation à partir d’un fichier de verrouillage npm, et un plugin qui définit des patchedDependencies Bun n’obtient aucune installation à partir de bun.lock
  • Délai d’expiration de 60 secondes : Claude Code arrête une installation qui s’exécute plus longtemps et la traite comme échouée
Claude Code récupère un plugin de source npm avant cette installation de dépendance, et aucun des scripts d’installation propres du package ne s’exécute pendant la récupération. Voir source de plugin npm. Vous ne pouvez pas désactiver l’installation automatique. Aucun paramètre ou variable d’environnement ne la désactive. Dans les réseaux restreints, voir les exigences d’accès réseau pour les hôtes à autoriser.

​
Quand l’installation de dépendance échoue ou est ignorée

Si l’installation échoue ou est ignorée, le plugin se charge quand même, mais les parties qui ont besoin des packages manquants peuvent ne pas fonctionner. /plugin et claude plugin list affichent une note sur un plugin activé dont la copie en cache contient un fichier de verrouillage et un package.json qui liste des dépendances d’exécution, mais aucun répertoire node_modules. La note indique si l’installation ne s’est pas terminée ou ne peut pas s’exécuter pour ce plugin. Consultez l’entrée de dépannage pour savoir que faire dans chaque cas. Quand l’installation automatique ne peut pas fournir une dépendance, installez-la à partir d’un hook dans le répertoire de données persistantes. Cela inclut les packages qui ont besoin de leurs scripts de cycle de vie pour compiler, les dépendances Python, les plugins verrouillés avec Yarn ou pnpm, et les dépendances qui ne sont pas des packages de registre, comme les dépendances git.

​
Versions et mises à jour

Si l’auteur d’un plugin a poussé de nouveaux commits et claude plugin update affiche <name> is already at the latest version (<version>)., la version que Claude Code calcule pour le plugin est inchangée, donc les fichiers du plugin sur disque ne changent pas. Claude Code calcule une version pour chaque plugin qu’il installe, et c’est ainsi qu’il détecte une mise à jour. claude plugin update et la mise à jour automatique en arrière-plan calculent la version à nouveau et ne remplacent pas la copie en cache quand elle correspond à ce que installed_plugins.json enregistre. Une mise à jour que vous lancez peut tout de même réessayer une installation de dépendance inachevée dans cette copie. La version nomme aussi le répertoire de cache du plugin. Un manifeste qui épingle "version" est une façon que la version calculée reste la même à travers les commits. Voir Comment Claude Code calcule la version pour l’ordre de résolution. Un plugin chargé en place depuis une marketplace que vous avez ajoutée à partir d’un chemin local charge ses fichiers source actuels à chaque démarrage de session, quoi que sa chaîne de version indique. Pour un plugin provenant d’une marketplace hébergée sur claude.ai, la version que claude.ai enregistre pour le plugin est sa version, et le version du manifeste n’est pas lu.

​
Comment Claude Code calcule la version

Pour un marché que vous avez ajouté par source, Claude Code choisit la règle par le type source de l’entrée de marché du plugin. La référence de marché liste les types de source. Pour chaque type de source dans cette liste sauf command :
  1. Le champ version dans le manifeste du plugin vient d’abord
  2. Puis le champ version dans l’entrée de marché du plugin
  3. Quand aucun n’est défini, la version vient du type de source :
Claude Code ne prend pas la version à partir d’un référentiel qui enferme le chemin d’installation, comme un ~/.claude géré par git. Pour une source command, Claude Code dérive toujours la version à partir de ce que la commande a produit : un hash de 12 caractères seul, ou <manifest version>-<hash> quand le manifeste en définit un. Le version de l’entrée de marché est ignoré pour les sources de commande. Pour ce que le hash couvre, voir Mode copie et mode lien. Parce que le manifeste vient d’abord, un manifeste qui épingle "version": "1.0.0" garde chaque utilisateur sur la copie en cache jusqu’à ce que son auteur change la chaîne, cependant de nombreux commits ils poussent. Pour laisser les utilisateurs suivre les commits à la place, laissez version hors du manifeste et de l’entrée. Héberger un marché couvre quel choix convient à quel setup de version.

​
Quand Claude Code actualise un marché avant une installation

Quand vous installez un plugin, Claude Code le cherche dans sa copie locale du catalogue de marché. Vous pouvez exécuter /plugin install dans une session ou claude plugin install dans votre shell, et nommer le plugin avec ou sans son marché. Le tableau montre laquelle de ces combinaisons actualise la copie locale. L’actualisation avant une installation name@marketplace ne dépend pas du paramètre d’auto-mise à jour du marché ou de DISABLE_AUTOUPDATER. Quand l’actualisation échoue, l’installation procède à partir du catalogue en cache et claude plugin install rapporte marketplace not refreshed. Claude Code ignore l’actualisation avant une installation name@marketplace quand :
  • Le marché a été ajouté à partir d’une source file ou directory locale, ou est défini en ligne dans les paramètres avec une source settings
  • Un répertoire de semence fournit le marché
  • Claude Code a actualisé le marché dans les 30 dernières secondes
  • Vous avez défini CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
  • Les paramètres gérés bloquent le marché, auquel cas Claude Code refuse aussi l’installation

​
Quand l’auto-mise à jour s’exécute

Dans une session interactive, après que vous ayez envoyé votre premier message, Claude Code attend un délai aléatoire jusqu’à dix minutes. Il actualise ensuite chaque marché avec l’auto-mise à jour activée et met à jour les plugins installés à partir d’eux sur disque. La session en cours garde les versions qu’elle a chargées, et vous voyez Plugin updated: <name> · Run /reload-plugins to apply. Que vous rechargiez ou non, les nouvelles versions se chargent au prochain lancement.

​
Quels marchés et plugins se mettent à jour automatiquement

Qu’un marché se mette à jour automatiquement suit le premier de ceux-ci qui est défini :
  1. autoUpdate sur son entrée extraKnownMarketplaces dans un fichier de paramètres
  2. autoUpdate sur son entrée known_marketplaces.json, que le bouton bascule Enable auto-update sous /plugin Marketplaces écrit. Quand un fichier de paramètres déclare aussi le marché sous extraKnownMarketplaces, le bouton bascule écrit autoUpdate à cette entrée de paramètres aussi
  3. La valeur par défaut : activée pour les marchés officiels d’Anthropic comme claude-plugins-official, désactivée pour knowledge-work-plugins et first-party-plugins, activée pour les marchés ajoutés à partir de claude.ai, et désactivée pour tous les autres marchés
Si vous définissez DISABLE_UPDATES=1, DISABLE_AUTOUPDATER=1, ou CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, le passage entier est désactivé et le bouton bascule Enable auto-update est caché, sauf si vous définissez aussi FORCE_AUTOUPDATE_PLUGINS=1. La référence des variables d’environnement couvre l’effet plus large de chaque variable. L’auto-mise à jour ignore aussi un plugin dont l’entrée de marché déclare un headersHelper. Les installations et mises à jour qui refusent une commande au lieu de demander expliquent quand un tel plugin apparaît dans l’onglet Errors de /plugin et comment vous le mettez à jour à partir de là. Quand un plugin copié se met à jour en milieu de session, les commandes de hook, les moniteurs, les serveurs MCP et les serveurs LSP continuent d’utiliser le chemin de la version précédente. Exécutez /reload-plugins pour basculer les hooks, les serveurs MCP et les serveurs LSP vers le nouveau chemin. Les moniteurs nécessitent un redémarrage de session.

​
Quand une source de commande se réexécute

Les plugins avec une source command n’attendent pas le passage d’auto-mise à jour. Le répertoire imprimé reflète l’état de l’outil au moment où la commande s’est exécutée, donc Claude Code exécute la commande que vous avez acceptée à nouveau à ces moments :
  • Chaque fois que vous installez ou mettez à jour le plugin
  • Une fois par session pour chaque plugin activé de source de commande, en arrière-plan, peu après le démarrage de la session. Cette exécution ne dépend pas du paramètre d’auto-mise à jour du marché ou de DISABLE_AUTOUPDATER
  • Au démarrage ou sur /reload-plugins, quand la version installée d’un plugin activé manque du cache de plugin
Claude Code ignore les deux exécutions en arrière-plan quand vous définissez CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Les installations et mises à jour explicites exécutent toujours la commande avec cette variable définie. Quand la sortie hachée de la commande a changé, Claude Code installe le résultat comme une nouvelle version et la recharge dans la session interactive en cours, basculant les mêmes composants que /reload-plugins bascule. Vous voyez une notification que le plugin a été rechargé. Si recharger en place invaliderait le cache d’invite de la session, Claude Code vous invite plutôt à exécuter /reload-plugins, qui avertit du coût du cache et s’applique quand réexécuté avec --force.

​
Conflits de noms

Quand les plugins activés de différentes origines partagent un nom de manifeste, cet ordre décide lequel se charge, de la plus haute à la plus basse précédence :
  1. Un plugin dont l’id apparaît dans les paramètres gérés enabledPlugins, comme true ou false. Une copie --plugin-dir dont le nom de manifeste correspond à la partie nom de l’id n’est pas chargée, et vous voyez --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings
  2. Un plugin --plugin-dir, --plugin-url, ou CLAUDE_CODE_PLUGIN_DIRS activé. Il remplace un plugin de marché installé ou de répertoire de compétences du même nom :
    • Un plugin de marché installé : remplacé silencieusement. claude plugin list affiche toujours la ligne du marché comme activée, car cette ligne reflète vos paramètres. Seul le journal que Claude Code écrit sous ~/.claude/debug/ quand vous démarrez avec --debug enregistre Plugin "<name>" from --plugin-dir overrides installed version
    • Un plugin de répertoire de compétences : remplacé par une ligne d’onglet Errors de /plugin qui lit Not loaded — the name "<name>" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence
  3. Un plugin de marché installé. Un plugin de répertoire de compétences du même nom obtient la même ligne Not loaded, nommant le plugin installé
  4. Un plugin de répertoire de compétences. Entre deux de ceux-ci, la copie sous ~/.claude/skills/ se charge et la copie .claude/skills/ du projet est supprimée, avec une ligne qui dit quel chemin l’a masquée
  5. Un plugin synchronisé à partir de claude.ai. Quand un plugin activé de toute autre origine correspond à son nom, Claude Code charge ce plugin et rapporte la copie synchronisée comme non chargée. Pour utiliser la copie claude.ai à la place, désactivez votre propre copie
Parce que l’ordre compare les noms de manifeste, un plugin --plugin-dir nommé hello-plugin remplace hello@example-marketplace quand ce plugin’s manifeste dit aussi "name": "hello-plugin".

​
Hooks lorsque deux plugins activés partagent un nom

Lorsque vous installez et activez deux plugins portant le même nom de manifeste depuis des marketplaces différentes, les deux apparaissent comme activés dans /plugin, mais les hooks de l’un d’eux sont laissés de côté. Un seul plugin par nom enregistre les hooks de son hooks/hooks.json, et un seul plugin par nom charge un module de hooks. Lorsque les paramètres gérés de votre organisation activent l’une des copies, c’est cette copie qui détient le nom. Sinon, c’est la copie que Claude Code charge en premier qui le détient. Pour voir quelle copie détient le nom, exécutez /plugin dans votre session et ouvrez l’onglet Errors. Une note y figure pour la copie dont les hooks ont été laissés de côté : elle nomme la copie qui détient le nom, et les détails de la copie laissée de côté affichent la même note. Pour les hooks hooks/hooks.json, la note commence par Its hooks.json hooks do not run, et pour un module de hooks, elle commence par Its hooks module does not load. La note nécessite Claude Code v2.1.296 ou une version ultérieure. Pour exécuter plutôt les hooks de la copie laissée de côté, désactivez ou désinstallez la copie qui détient le nom, puis exécutez /reload-plugins dans votre session. Le rechargement enregistre les hooks de la copie restante et efface la note. Lorsque la copie qui détient le nom est activée par vos paramètres gérés, vous ne pouvez pas la désactiver, et les hooks de l’autre copie restent désactivés tant que les deux sont installées.

​
Empêcher un plugin de session uniquement de se charger

Pour empêcher un plugin --plugin-dir de masquer quoi que ce soit, ou pour en désactiver un quand un processus parent passe l’indicateur pour vous, définissez son id à false dans n’importe quel fichier de paramètres. Pour un plugin dont le nom de manifeste est hello-plugin, l’entrée est "enabledPlugins": {"hello-plugin@inline": false}. Un plugin de session uniquement désactivé ne masque pas, donc la copie de marché ou de répertoire de compétences se charge à la place.

​
Étapes suivantes