plugin-hints.md +0 −172 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Recommander votre plugin depuis votre CLI
6
7> Émettez un marqueur d'une ligne depuis votre CLI pour que Claude Code invite les utilisateurs à installer votre plugin officiel.
8
9Si vous maintenez une CLI ou un SDK et disposez d'un plugin dans la marketplace officielle d'Anthropic, votre outil peut inviter les utilisateurs de Claude Code à installer ce plugin. Votre CLI écrit un marqueur d'une ligne sur stderr lorsqu'elle détecte qu'elle s'exécute dans Claude Code. Claude Code lit le marqueur, le supprime de la sortie et affiche à l'utilisateur une invite d'installation unique.
10
11Le protocole ne nécessite aucune commande supplémentaire et ne change pas ce que votre CLI affiche pour les utilisateurs en dehors de Claude Code.
12
13Cette page est destinée aux mainteneurs de CLI et de SDK. Si vous cherchez à installer des plugins, consultez [Découvrir et installer des plugins](/docs/fr/discover-plugins).
14
15<h2 id="how-it-works">
16 Fonctionnement
17</h2>
18
19Claude Code définit la variable d'environnement [`CLAUDECODE`](/docs/fr/env-vars) à `1` pour chaque commande qu'elle exécute via les outils Bash et PowerShell, et pour les commandes [hook](/docs/fr/hooks). À partir de la v2.1.172, elle définit également [`CLAUDE_CODE_CHILD_SESSION`](/docs/fr/env-vars) à `1` dans ces mêmes sous-processus. Lorsque votre CLI voit l'une de ces variables, elle écrit une balise auto-fermante `<claude-code-hint />` sur stderr. Dans les commandes hook, la balise d'indice est supprimée et ignorée. Seule la sortie des outils Bash et PowerShell déclenche l'invite d'installation.
20
21Lorsque Claude Code reçoit la sortie de la commande, elle :
22
231. Analyse les lignes d'indice et les supprime avant que la sortie n'atteigne le modèle
242. Vérifie que l'indice cible un plugin dans une marketplace officielle d'Anthropic
253. Vérifie que le plugin n'est pas déjà installé et n'a pas été proposé auparavant
264. Affiche à l'utilisateur une invite d'installation qui nomme la commande qui a émis l'indice
27
28Claude Code n'installe jamais un plugin automatiquement. L'utilisateur confirme toujours.
29
30<h2 id="emit-the-hint">
31 Émettre l'indice
32</h2>
33
34Les invites d'indice ne s'activent que pour les plugins listés sur la marketplace officielle d'Anthropic. Consultez [Faire entrer votre plugin dans la marketplace officielle](#get-your-plugin-into-the-official-marketplace) avant de déployer l'intégration.
35
36Conditionnez l'émission sur une variable d'environnement afin que le marqueur soit peu probable d'apparaître lorsqu'un humain exécute votre CLI directement, puis écrivez la balise sur stderr sur sa propre ligne. Choisissez quelle variable vérifier :
37
38* `CLAUDECODE` : défini sur chaque version de Claude Code, il atteint donc le plus de sessions. Il est également défini dans les sessions tmux et les sous-processus du serveur MCP stdio que Claude Code démarre. Les extensions IDE le définissent également dans leurs terminaux intégrés, où un humain peut exécuter votre CLI directement.
39* `CLAUDE_CODE_CHILD_SESSION` : défini uniquement dans les sous-processus que Claude Code lui-même génère, tels que les appels d'outils, les commandes hook et les commandes de [ligne d'état](/docs/fr/statusline), afin que la balise n'atteigne normalement pas un terminal humain. Un processus de longue durée qui a été démarré à l'intérieur d'une session, comme un serveur tmux, capture la variable, de sorte que les shells lancés ultérieurement à partir de ce processus affichent toujours la balise brute.
40
41Les exemples suivants conditionnent sur `CLAUDECODE` pour une portée maximale et émettent un indice pour un plugin nommé `example-cli` dans la marketplace officielle :
42
43<CodeGroup>
44 ```javascript Node.js theme={null}
45 if (process.env.CLAUDECODE) {
46 process.stderr.write(
47 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
48 )
49 }
50 ```
51
52 ```python Python theme={null}
53 import os, sys
54
55 if os.environ.get("CLAUDECODE"):
56 print(
57 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
58 file=sys.stderr,
59 )
60 ```
61
62 ```go Go theme={null}
63 if os.Getenv("CLAUDECODE") != "" {
64 fmt.Fprintln(os.Stderr,
65 `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
66 }
67 ```
68
69 ```shell Shell theme={null}
70 if [ -n "$CLAUDECODE" ]; then
71 printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
72 fi
73 ```
74</CodeGroup>
75
76Remplacez `example-cli` par le nom de votre plugin dans la marketplace officielle.
77
78<h2 id="choose-where-to-emit">
79 Choisir où émettre
80</h2>
81
82Vous contrôlez les chemins de code qui émettent l'indice. Claude Code déduplique par plugin, donc émettre à chaque invocation n'a aucun inconvénient. Les points de contact qui fonctionnent bien incluent :
83
84| Placement | Pourquoi cela fonctionne |
85| :----------------------------------------- | :--------------------------------------------------------------------- |
86| Sortie `--help` | Claude exécute souvent l'aide lors de l'exploration d'une CLI inconnue |
87| Erreurs de sous-commande inconnue | Atteint le moment où Claude est confus par votre interface |
88| Succès de connexion ou d'authentification | L'utilisateur est déjà dans un état d'esprit de configuration |
89| Message de bienvenue de première exécution | Un moment d'intégration naturel |
90
91<h2 id="what-the-user-sees">
92 Ce que voit l'utilisateur
93</h2>
94
95Lorsque l'indice passe tous les contrôles, Claude Code affiche une invite comme la suivante :
96
97```text theme={null}
98─────────────────────────────────────────────────────────────
99 Recommandation de plugin
100
101 La commande example-cli suggère d'installer un plugin.
102
103 Plugin : example-cli
104 Marketplace : claude-plugins-official
105 Intégration officielle pour les déploiements example-cli
106
107 Voulez-vous l'installer ?
108 ❯ 1. Oui, installer example-cli
109 2. Non
110 3. Non, et ne plus afficher les suggestions d'installation de plugins
111
112─────────────────────────────────────────────────────────────
113```
114
115L'invite nomme la commande qui a produit l'indice afin que les utilisateurs puissent détecter une discordance entre l'outil et le plugin qu'il recommande. Si l'utilisateur ne répond pas dans les 30 secondes, Claude Code rejette l'invite en tant que **Non**.
116
117La fréquence des invites est limitée, et certaines sessions ne proposent jamais d'invite :
118
119* **Une fois par plugin** : après l'affichage de l'invite, Claude Code enregistre le plugin et ne le propose jamais plus, quel que soit la réponse de l'utilisateur.
120* **Une fois par session** : sur tous les CLIs de la machine, au maximum une invite d'indice apparaît par session Claude Code.
121* **Session interactive principale uniquement** : Claude Code affiche l'invite uniquement dans la session de terminal dans laquelle l'utilisateur tape. Claude Code ne propose jamais d'invite pour une commande qu'un [sous-agent](/docs/fr/sub-agents) exécute, et ne propose jamais d'invite lorsque l'utilisateur exécute Claude Code en [mode non interactif](/docs/fr/headless) avec l'indicateur `-p` ou via le [SDK Agent](/docs/fr/agent-sdk/overview). Claude Code supprime toujours la ligne d'indice de la sortie de la commande dans tous ces cas.
122* **Désactivations de télémétrie** : les sessions où l'analyse est désactivée ne montrent jamais d'invites d'indice. Cela inclut les sessions avec `DISABLE_TELEMETRY` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` définis, et les sessions sur des fournisseurs tiers tels qu'Amazon Bedrock ou la plateforme Agent de Google Cloud où la [désactivation automatique de la télémétrie](/docs/fr/data-usage#default-behaviors-by-api-provider) s'applique.
123
124Sélectionner **Oui** installe le plugin à la portée utilisateur. Sélectionner **Non, et ne plus afficher les suggestions d'installation de plugins** désactive toutes les futures invites d'indice pour l'utilisateur.
125
126<h2 id="hint-format">
127 Format de l'indice
128</h2>
129
130L'indice est une balise auto-fermante avec trois attributs requis.
131
132```text theme={null}
133<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
134```
135
136| Attribut | Requis | Description |
137| :------- | :----- | :------------------------------------------------------------ |
138| `v` | Oui | Version du protocole. `1` est la seule valeur prise en charge |
139| `type` | Oui | Type d'indice. `plugin` est la seule valeur prise en charge |
140| `value` | Oui | Identifiant du plugin sous la forme `name@marketplace` |
141
142Les valeurs d'attribut peuvent être entre guillemets doubles ou sans guillemets. Les valeurs sans guillemets ne peuvent pas contenir d'espaces. Les séquences d'échappement ne sont pas prises en charge.
143
144<h2 id="requirements">
145 Exigences
146</h2>
147
148Claude Code applique deux conditions avant d'agir sur un indice. Les indices qui échouent à l'un des contrôles sont supprimés :
149
150* **Ligne propre** : la balise doit occuper sa propre ligne. Une balise intégrée au milieu d'une ligne, par exemple à l'intérieur d'une instruction de journal, est ignorée. Les espaces blancs de début et de fin sur la ligne sont autorisés.
151* **Marketplace officielle** : la `value` doit référencer un plugin dans une marketplace contrôlée par Anthropic, telle que `claude-plugins-official`. Les indices pointant vers d'autres marketplaces sont silencieusement supprimés.
152
153La ligne d'indice est toujours supprimée de la sortie avant qu'elle n'atteigne le modèle, même lorsque la version ou le type n'est pas reconnu, de sorte que le marqueur n'est jamais comptabilisé dans l'utilisation des tokens.
154
155Les conseils restants sont recommandés mais non appliqués. Claude Code ne peut pas observer si votre CLI les suit :
156
157* **Écrire sur stderr** : stderr garde la balise hors des pipelines shell tels que `example-cli deploy | jq`. Claude Code analyse les deux flux, donc stdout fonctionne aussi.
158* **Conditionner sur une variable d'environnement** : n'émettez que lorsque `CLAUDECODE` ou `CLAUDE_CODE_CHILD_SESSION` est défini. Consultez [Émettre l'indice](#emit-the-hint) pour savoir comment les deux variables diffèrent.
159
160<h2 id="get-your-plugin-into-the-official-marketplace">
161 Obtenir votre plugin dans la marketplace officielle
162</h2>
163
164Le protocole d'indice ne prend effet que pour les plugins répertoriés dans la marketplace officielle d'Anthropic, `claude-plugins-official`. Anthropic gère cette marketplace à sa discrétion, et les formulaires de soumission intégrés à l'application ajoutent des plugins à la [marketplace communautaire](/docs/fr/plugins#submit-your-plugin-to-the-community-marketplace) à la place, que le protocole d'indice ne vérifie pas. Si vous travaillez avec un contact partenaire d'Anthropic, contactez-le pour coordonner une inscription à la marketplace officielle.
165
166<h2 id="see-also">
167 Voir aussi
168</h2>
169
170* [Créer des plugins](/docs/fr/plugins) : créez le plugin que votre CLI recommande
171* [Créer et distribuer une marketplace de plugins](/docs/fr/plugin-marketplaces) : hébergez des plugins en dehors de la marketplace officielle
172* [Variables d'environnement](/docs/fr/env-vars) : référence complète pour `CLAUDECODE` et les variables associées