Consiglia il tuo plugin dalla tua CLI

Se gestisci una CLI o un SDK, il tuo strumento può invitare gli utenti di Claude Code a installare il tuo plugin. Quando la tua CLI rileva che è in esecuzione all’interno di Claude Code, fai in modo che scriva un tag <claude-code-hint /> su una singola riga verso stderr. Claude Code rimuove la riga dall’output dello strumento Bash e PowerShell prima che il modello veda l’output, quindi mostra all’utente un prompt di installazione una sola volta. Questa pagina si applica solo se il tuo plugin è elencato in claude-plugins-official o in un altro marketplace con uno dei nomi ufficiali del marketplace di Anthropic. Il marketplace della comunità, claude-community, non è uno di questi.

Per pubblicare un plugin, vedi Pubblica e distribuisci un plugin.

Emetti l’hint

Emetti il tag solo quando CLAUDECODE o CLAUDE_CODE_CHILD_SESSION è impostato, in modo che non appaia quando una persona esegue la tua CLI direttamente. Claude Code imposta CLAUDECODE=1 nei comandi che esegue attraverso gli strumenti Bash e PowerShell e nei comandi hook. Dalla versione 2.1.172 in poi imposta anche CLAUDE_CODE_CHILD_SESSION=1 lì. Le variabili differiscono nei processi che le portano:

CLAUDECODE: impostato da ogni versione di Claude Code. Le estensioni IDE lo impostano anche nei loro terminali integrati, quindi un gate su CLAUDECODE da solo emette il tag anche quando una persona esegue la tua CLI direttamente in uno di questi terminali
CLAUDE_CODE_CHILD_SESSION: impostato solo nei sottoprocessi che Claude Code stesso avvia. Usalo quando puoi richiedere la versione 2.1.172 o successiva

Il riferimento delle variabili di ambiente contiene i dettagli. I seguenti esempi usano un gate su CLAUDECODE per la massima portata ed emettono un hint 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',
  )
}

import os, sys

if os.environ.get("CLAUDECODE"):
    print(
        '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
        file=sys.stderr,
    )

if os.Getenv("CLAUDECODE") != "" {
    fmt.Fprintln(os.Stderr,
        `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
}

if [ -n "$CLAUDECODE" ]; then
  printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
fi

Sostituisci example-cli con il nome del tuo plugin nel marketplace ufficiale. Puoi emettere l’hint ad ogni invocazione, perché Claude Code chiede per ogni plugin una sola volta. Per verificare l’emettitore, esegui CLAUDECODE=1 example-cli in un terminale e conferma che la riga del tag appaia su stderr, quindi esegui example-cli senza la variabile e conferma che non stampi nulla di extra.

Formato dell’hint

Il tag deve occupare la sua propria riga; Claude Code ignora un tag incorporato a metà riga. Il tag accetta tre attributi, tutti obbligatori:

Attributo	Descrizione
`v`	Versione del protocollo. `1` è l’unico valore supportato
`type`	Tipo di hint. `plugin` è l’unico valore supportato
`value`	Identificatore del plugin nella forma `name@marketplace`

I valori possono essere tra virgolette doppie o senza virgolette; un valore senza virgolette non può contenere spazi. Claude Code rimuove la riga dall’output anche quando v o type non è riconosciuto.

Verifica quando appare il prompt

Il prompt appare solo nelle sessioni di terminale interattive. Nelle esecuzioni claude -p, nelle esecuzioni di subagent e nell’output dei comandi hook, il tag viene rimosso e nessun prompt viene mostrato. Tutti questi controlli devono anche passare:

Ufficiale e installabile: value nomina un plugin che Claude Code trova nella sua copia locale di un marketplace ufficiale, che non è già installato e che nessuna policy blocca
Analytics attivato: una sessione in cui gli analytics di Claude Code sono disattivati non chiede mai, ad esempio una con DISABLE_TELEMETRY, DO_NOT_TRACK o CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC impostato, o una su un provider di terze parti come Amazon Bedrock, dove si applica l’opt-out automatico della telemetria
Limiti di frequenza: un prompt per sessione, un prompt mai per plugin indipendentemente dalla risposta dell’utente, e nessuno una volta che 100 plugin sono stati richiesti su quella macchina
Non disattivato: l’utente non ha scelto No, e non mostrare più gli hint di installazione dei plugin
Sessione locale e presidiata: lo spazio di lavoro della sessione è locale piuttosto che su una macchina cloud o remota, e la sessione non è in esecuzione incustodita. Ad esempio, una sessione avviata con --cloud, una che serve Remote Control, o un compagno di squadra agent-team non chiede mai

Anteprima di ciò che vede l’utente

Quando i controlli in Verifica quando appare il prompt passano, Claude Code mostra una finestra di dialogo Plugin recommendation come la seguente:

─────────────────────────────────────────────────────────────
  Plugin recommendation

    The example-cli command suggests installing a plugin.

    Plugin: example-cli
    Marketplace: claude-plugins-official
    Description: Official integration for example-cli deployments

    Would you like to install it?
    ❯ 1. Yes, install
      2. No
      3. No, and don't show plugin installation hints again

─────────────────────────────────────────────────────────────

La finestra di dialogo nomina la prima parola del comando shell che Claude ha eseguito, in modo che gli utenti possano individuare una mancata corrispondenza. Ogni risposta ha un effetto:

Yes, install: installa il plugin a user scope
No, and don’t show plugin installation hints again: disattiva i futuri prompt di hint per quell’utente
Nessuna risposta per 30 secondi: conta come No

Passaggi successivi

Pubblica e distribuisci un plugin: i percorsi in ogni marketplace, incluso il marketplace ufficiale, che l’hint richiede
Riferimento dei comandi dei plugin: il comando shell che installa lo stesso plugin al di fuori di una sessione

Plugin

Usa i plugin

Crea plugin

Eseguire un marketplace

Gestisci i plugin per la tua organizzazione

Risoluzione dei problemi

Riferimento

Consiglia il tuo plugin dalla tua CLI

Emetti l’hint

Formato dell’hint

Verifica quando appare il prompt

Anteprima di ciò che vede l’utente

Passaggi successivi

​Emetti l’hint

​Formato dell’hint

​Verifica quando appare il prompt

​Anteprima di ciò che vede l’utente

​Passaggi successivi

Emetti l’hint

Formato dell’hint

Verifica quando appare il prompt

Anteprima di ciò che vede l’utente

Passaggi successivi