Skip to main content

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.

Se 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. Claude 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. Questa pagina è per i manutentori di CLI e SDK. Se stai cercando di installare plugin, vedi Scopri e installa plugin.

​
Come funziona

Claude Code imposta la variabile di ambiente CLAUDECODE a 1 per ogni comando che esegue attraverso gli strumenti Bash e PowerShell. Quando la tua CLI vede quella variabile, scrive un tag <claude-code-hint /> auto-chiudente in stderr. Quando Claude Code riceve l’output del comando, esegue le seguenti operazioni:
  1. Scansiona le righe di suggerimento e le rimuove prima che l’output raggiunga il modello
  2. Verifica che il suggerimento sia destinato a un plugin in un marketplace ufficiale di Anthropic
  3. Verifica che il plugin non sia già installato e che non sia stato suggerito in precedenza
  4. Mostra all’utente un prompt di installazione che nomina il comando che ha emesso il suggerimento
Claude Code non installa mai un plugin automaticamente. L’utente conferma sempre.

​
Emetti il suggerimento

Condiziona 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. I seguenti esempi emettono un suggerimento per un plugin denominato example-cli nel marketplace ufficiale: 
if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
  )
}
Sostituisci example-cli con il nome del tuo plugin nel marketplace ufficiale.

​
Scegli dove emettere

Controlli 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:
PosizionamentoPerché funziona
Output di --helpClaude spesso esegue help quando esplora una CLI sconosciuta
Errori di sottocomando sconosciutoRaggiunge il momento in cui Claude è confuso sulla tua interfaccia
Accesso o successo dell’autenticazioneL’utente è già in uno stato mentale di configurazione
Messaggio di benvenuto al primo avvioUn momento di onboarding naturale

​
Cosa vede l’utente

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

    Il comando example-cli suggerisce di installare un plugin.

    Plugin: example-cli
    Marketplace: claude-plugins-official
    Integrazione ufficiale per distribuzioni example-cli

    Desideri installarlo?
    ❯ 1. Sì, installa example-cli
      2. No
      3. No, e non mostrare più suggerimenti di installazione plugin

─────────────────────────────────────────────────────────────
Il 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. La frequenza del prompt è limitata:
  • 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.
  • Una volta per sessione: su tutte le CLI della macchina, al massimo un suggerimento di prompt appare per sessione di Claude Code.
Selezionando 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.

​
Formato del suggerimento

Il suggerimento è un tag auto-chiudente con tre attributi obbligatori. 
<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
AttributoObbligatorioDescrizione
vSìVersione del protocollo. 1 è l’unico valore supportato
typeSìTipo di suggerimento. plugin è l’unico valore supportato
valueSìIdentificatore del plugin nella forma name@marketplace
I 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.

​
Requisiti

Claude Code applica due condizioni prima di agire su un suggerimento. I suggerimenti che non superano nessuno dei due controlli vengono scartati:
  • 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.
  • 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.
La 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. Le linee guida rimanenti sono consigliate ma non applicate. Claude Code non può osservare se la tua CLI le segue:
  • 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.
  • 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.

​
Inserisci il tuo plugin nel marketplace ufficiale

Il protocollo di suggerimento ha effetto solo per i plugin elencati nel marketplace ufficiale di Anthropic. Per inviare un plugin, utilizza uno dei moduli di invio in-app: Se stai lavorando con un contatto partner di Anthropic, contattalo per coordinare l’elenco.

​
Vedi anche