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# Consiglia il tuo plugin dalla tua CLI

6 

7> Emetti un marcatore su una riga dalla tua CLI in modo che Claude Code chieda agli utenti di installare il tuo plugin ufficiale.

8 

9Se mantieni una CLI o SDK e hai un plugin nel marketplace ufficiale di Anthropic, il tuo strumento può chiedere agli utenti di Claude Code di installare quel plugin. La tua CLI scrive un marcatore su una riga in stderr quando rileva che è in esecuzione all'interno di Claude Code. Claude Code legge il marcatore, lo rimuove dall'output e mostra all'utente un prompt di installazione una sola volta.

10 

11Claude Code rimuove la riga di suggerimento dall'output del comando prima di inviarlo al modello, quindi il marcatore non appare mai nella conversazione e non viene conteggiato verso l'utilizzo dei token. Il protocollo non richiede comandi extra e non cambia ciò che la tua CLI stampa per gli utenti al di fuori di Claude Code.

12 

13Questa pagina è per i manutentori di CLI e SDK. Se stai cercando di installare plugin, vedi [Scopri e installa plugin](/it/discover-plugins).

14 

15<h2 id="how-it-works">

16 Come funziona

17</h2>

18 

19Claude Code imposta la variabile di ambiente [`CLAUDECODE`](/it/env-vars) a `1` per ogni comando che esegue attraverso gli strumenti Bash e PowerShell, e per i comandi [hook](/it/hooks). Quando la tua CLI vede quella variabile, scrive un tag `<claude-code-hint />` auto-chiudente in stderr. Nei comandi hook il tag di suggerimento viene rimosso e ignorato. Solo l'output degli strumenti Bash e PowerShell attiva il prompt di installazione.

20 

21Quando Claude Code riceve l'output del comando, esegue le seguenti operazioni:

22 

231. Scansiona le righe di suggerimento e le rimuove prima che l'output raggiunga il modello

242. Verifica che il suggerimento sia destinato a un plugin in un marketplace ufficiale di Anthropic

253. Verifica che il plugin non sia già installato e che non sia stato suggerito in precedenza

264. Mostra all'utente un prompt di installazione che nomina il comando che ha emesso il suggerimento

27 

28Claude Code non installa mai un plugin automaticamente. L'utente conferma sempre.

29 

30<h2 id="emit-the-hint">

31 Emetti il suggerimento

32</h2>

33 

34Condiziona l'emissione sulla variabile di ambiente `CLAUDECODE` in modo che il marcatore non appaia mai nel terminale di un utente umano. Quindi scrivi il tag in stderr sulla sua propria riga.

35 

36I seguenti esempi emettono un suggerimento per un plugin denominato `example-cli` nel marketplace ufficiale:

37 

38<CodeGroup>

39 ```javascript Node.js theme={null}

40 if (process.env.CLAUDECODE) {

41 process.stderr.write(

42 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',

43 )

44 }

45 ```

46 

47 ```python Python theme={null}

48 import os, sys

49 

50 if os.environ.get("CLAUDECODE"):

51 print(

52 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',

53 file=sys.stderr,

54 )

55 ```

56 

57 ```go Go theme={null}

58 if os.Getenv("CLAUDECODE") != "" {

59 fmt.Fprintln(os.Stderr,

60 `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)

61 }

62 ```

63 

64 ```shell Shell theme={null}

65 [ -n "$CLAUDECODE" ] &&

66 printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2

67 ```

68</CodeGroup>

69 

70Sostituisci `example-cli` con il nome del tuo plugin nel marketplace ufficiale.

71 

72<h2 id="choose-where-to-emit">

73 Scegli dove emettere

74</h2>

75 

76Controlli quali percorsi di codice emettono il suggerimento. Claude Code deduplica per plugin, quindi emettere ad ogni invocazione non ha alcun aspetto negativo. I punti di contatto che funzionano bene includono:

77 

78| Posizionamento | Perché funziona |

79| :------------------------------------- | :----------------------------------------------------------------- |

80| Output di `--help` | Claude spesso esegue help quando esplora una CLI sconosciuta |

81| Errori di sottocomando sconosciuto | Raggiunge il momento in cui Claude è confuso sulla tua interfaccia |

82| Accesso o successo dell'autenticazione | L'utente è già in uno stato mentale di configurazione |

83| Messaggio di benvenuto al primo avvio | Un momento di onboarding naturale |

84 

85<h2 id="what-the-user-sees">

86 Cosa vede l'utente

87</h2>

88 

89Quando il suggerimento supera tutti i controlli, Claude Code mostra un prompt come il seguente:

90 

91```text theme={null}

92─────────────────────────────────────────────────────────────

93 Raccomandazione Plugin

94 

95 Il comando example-cli suggerisce di installare un plugin.

96 

97 Plugin: example-cli

98 Marketplace: claude-plugins-official

99 Integrazione ufficiale per distribuzioni example-cli

100 

101 Desideri installarlo?

102 ❯ 1. Sì, installa example-cli

103 2. No

104 3. No, e non mostrare più suggerimenti di installazione plugin

105 

106─────────────────────────────────────────────────────────────

107```

108 

109Il prompt nomina il comando che ha prodotto il suggerimento in modo che gli utenti possano individuare una mancata corrispondenza tra lo strumento e il plugin che consiglia. Se l'utente non risponde entro 30 secondi, il prompt viene chiuso come **No**.

110 

111La frequenza del prompt è limitata:

112 

113* **Una volta per plugin**: dopo che il prompt viene mostrato, Claude Code registra il plugin e non lo suggerisce mai più, indipendentemente dalla risposta dell'utente.

114* **Una volta per sessione**: su tutte le CLI della macchina, al massimo un suggerimento di prompt appare per sessione di Claude Code.

115 

116Selezionando **Sì** installa il plugin nell'ambito dell'utente. Selezionando **No, e non mostrare più suggerimenti di installazione plugin** disabilita tutti i futuri suggerimenti di prompt per l'utente.

117 

118<h2 id="hint-format">

119 Formato del suggerimento

120</h2>

121 

122Il suggerimento è un tag auto-chiudente con tre attributi obbligatori.

123 

124```text theme={null}

125<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />

126```

127 

128| Attributo | Obbligatorio | Descrizione |

129| :-------- | :----------- | :--------------------------------------------------------- |

130| `v` | Sì | Versione del protocollo. `1` è l'unico valore supportato |

131| `type` | Sì | Tipo di suggerimento. `plugin` è l'unico valore supportato |

132| `value` | Sì | Identificatore del plugin nella forma `name@marketplace` |

133 

134I valori degli attributi possono essere racchiusi tra virgolette doppie o lasciati senza virgolette. I valori senza virgolette non possono contenere spazi. Le sequenze di escape non sono supportate.

135 

136<h2 id="requirements">

137 Requisiti

138</h2>

139 

140Claude Code applica due condizioni prima di agire su un suggerimento. I suggerimenti che non superano nessuno dei due controlli vengono scartati:

141 

142* **Riga propria**: il tag deve occupare la sua propria riga. Un tag incorporato a metà riga, ad esempio all'interno di un'istruzione di log, viene ignorato. Gli spazi bianchi iniziali e finali sulla riga sono consentiti.

143* **Marketplace ufficiale**: il `value` deve fare riferimento a un plugin in un marketplace controllato da Anthropic come `claude-plugins-official`. I suggerimenti che puntano ad altri marketplace vengono silenziosamente scartati.

144 

145La riga di suggerimento viene sempre rimossa dall'output prima che raggiunga il modello, anche quando la versione o il tipo non è riconosciuto, quindi il marcatore non viene mai conteggiato verso l'utilizzo dei token.

146 

147Le linee guida rimanenti sono consigliate ma non applicate. Claude Code non può osservare se la tua CLI le segue:

148 

149* **Scrivi in stderr**: stderr mantiene il tag fuori dalle pipeline di shell come `example-cli deploy | jq`. Claude Code scansiona entrambi i flussi, quindi anche stdout funziona.

150* **Condiziona su `CLAUDECODE`**: emetti solo quando la variabile di ambiente `CLAUDECODE` è impostata. Questo impedisce al marcatore di apparire agli utenti che eseguono la tua CLI direttamente.

151 

152<h2 id="get-your-plugin-into-the-official-marketplace">

153 Inserisci il tuo plugin nel marketplace ufficiale

154</h2>

155 

156Il protocollo di suggerimento ha effetto solo per i plugin elencati nel marketplace ufficiale di Anthropic, `claude-plugins-official`. Anthropic cura quel marketplace a sua discrezione, e i moduli di invio in-app aggiungono plugin al [marketplace della comunità](/it/plugins#submit-your-plugin-to-the-community-marketplace) invece, che il protocollo di suggerimento non controlla. Se stai lavorando con un contatto partner di Anthropic, contattalo per coordinare un elenco nel marketplace ufficiale.

157 

158<h2 id="see-also">

159 Vedi anche

160</h2>

161 

162* [Crea plugin](/it/plugins): costruisci il plugin che la tua CLI consiglia

163* [Crea e distribuisci un marketplace di plugin](/it/plugin-marketplaces): ospita plugin al di fuori del marketplace ufficiale

164* [Variabili di ambiente](/it/env-vars): riferimento completo per `CLAUDECODE` e variabili correlate