SpyBara
Go Premium

plugins/mods/reference.md 2026-10-01 23:59 UTC to 2026-10-02 22:00 UTC

This page contains 326 additions and 0 deletions.

2026
Fri 2 22:59

Riferimento dei mod

Riferimento completo per i mod di Claude Code: struttura del modulo degli hook, eventi, metodi dell'API dei mod, punti di rendering, elementi per superficie, limiti e impostazioni.

Consulta qualsiasi evento che un mod può gestire, qualsiasi metodo dell'API dei mod che può chiamare o qualsiasi punto di rendering in cui può disegnare, per la CLI di Claude Code e l'app Desktop a partire dalla v2.1.287. Ogni voce riporta il nome e una descrizione di una riga e, dove presente, rimanda alla sezione della guida che lo spiega.

File

Un mod è una directory di plugin con questi file:

File Obbligatorio Contenuto
.claude-plugin/plugin.json Sì Il manifest del plugin. I mod non aggiungono campi obbligatori.
hooks/hooks.json Sì modules: un array con un percorso, relativo a questo file, al modulo degli hook, come in "modules": ["./register.js"]. Può contenere anche hook delle impostazioni sotto hooks.
Il modulo degli hook, ad esempio hooks/register.js Sì Il punto di ingresso del mod. Esporta register(on, options). Con estensione .js, .mjs, .cjs, .jsx, .ts, .mts, .cts o .tsx. Un modulo ES.
types/index.d.ts, indicato da types nel manifest Quando il mod usa $.state o aggiunge un namespace all'API dei mod Dichiara i valori di PluginState e qualsiasi namespace aggiunto dal mod
File i cui nomi terminano con .test.ts o .test.tsx No Test eseguiti da claude plugin test

register riceve on e options. options contiene i valori dei campi userConfig dichiarati dal manifest, con i valori predefiniti compilati.

La funzione hook

Un mod registra ciascuno dei suoi hook, che sono gestori di eventi, chiamando on all'interno di register. on accetta il nome dell'evento, un matcher facoltativo, che è un filtro sui campi dell'evento, e l'hook, come in on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on restituisce una registrazione con un solo metodo, .catch(handler), che imposta il gestore degli errori dell'hook.

Argomento Che cos'è
$ L'API dei mod: ogni metodo in metodi dell'API dei mod. Scrivi ogni chiamata per intero, prima il namespace e poi il metodo, come in $.fs.read('notes.md').
e L'input dell'evento, come dati semplici congelati in profondità. Per modificarlo, passa una copia a next.
next(e) Il gestore successivo, come in un middleware. Esegue gli hook successivi a questo, poi il comportamento di Claude Code. Si risolve nel risultato dell'evento.
next.signal Un AbortSignal che si interrompe quando l'evento viene abbandonato
next.origin { plugin, tier } di chi ha generato l'evento. Claude Code stesso è { plugin: 'engine', tier: 'core' }. Il tier di un mod è il suo gruppo di priorità nell'ordine in cui vengono eseguiti i mod: prepend, user, append o builtin.
next.budget Il limite di tempo dell'hook in millisecondi: next.budget.ms è il limite complessivo e next.budget.remainingMs è il tempo rimanente in quel momento
next.to(e, tier) Salta a un tier successivo, che può essere append, builtin o core. next.to(e, 'append') salta i mod installati da un utente. Solo un mod in prependPlugins o appendPlugins può chiamarlo.
next.error, next.called Solo in un gestore .catch. next.error.kind è throw o timeout, next.error.message è il testo dell'errore e next.called è true quando l'hook non riuscito aveva chiamato next.

Eventi

Gli eventi sono raggruppati in base a ciò che riguardano, ciascuno con il momento in cui si attiva e ciò che un hook su di esso può restituire. Gli hook su turn.step e process.spawn sono generatori asincroni, mentre gli altri hook sono funzioni asincrone.

L'ultima colonna di ogni tabella usa una notazione abbreviata. next(e) passa l'evento senza modificarlo. next({ ...e, text }) passa una copia con il campo indicato modificato, come in next({ ...e, text: e.text.trim() }). Un oggetto risponde all'evento senza chiamare next, e una parola come reason indica una stringa che scrivi tu, come in { deny: 'Use the file tools.' }.

Strumenti

Gli eventi degli strumenti si attivano attorno a ogni chiamata a uno strumento effettuata da Claude, dalla descrizione che Claude legge fino alla decisione se la chiamata viene eseguita:

Evento Si attiva quando Un hook può restituire
tool.call Uno strumento sta per essere eseguito next(e), { deny: reason } oppure { result }
tool.check Claude Code decide se una chiamata a uno strumento può essere eseguita, dopo gli hook tool.call e PreToolUse. next(e) si risolve nella decisione raggiunta dalle regole, dalla modalità di permesso e da quegli hook. { decision }, che è allow, ask o deny
tool.describe Una volta per ogni strumento, quando la sua descrizione viene inviata per la prima volta a Claude { description }

Prompt e ciò che Claude legge

Gli eventi dei prompt riguardano il testo che l'utente digita e il testo che Claude Code invia a Claude di propria iniziativa, come il prompt di sistema e i promemoria:

Evento Si attiva quando Un hook può restituire
prompt.submit Viene inviato un prompt next({ ...e, text }), next({ ...e, context }) oppure { drop: reason }
prompt.fill, prompt.suggest Del testo sta per essere inserito nella casella del prompt come bozza o come suggerimento attenuato next(e) con il testo modificato
prompt.edit L'utente modifica la casella del prompt next(e)
prompt.compose Claude Code genera un prompt di sistema { sections }, un elenco di { id, text, scope } nell'ordine in cui vengono inviati
prompt.section Una volta per ogni sezione con nome del prompt di sistema. e.name è l'id della sezione in prompt.compose. { text } oppure { text: null } per omettere la sezione
prompt.context Una volta per ogni conversazione, per il contesto inviato con il primo messaggio { blocks }
prompt.attachment Claude Code aggiunge un proprio messaggio per Claude, come un promemoria. e.type indica il tipo e, per i tipi dichiarati dalle definizioni dei tipi, e.detail contiene i dati a partire dai quali è stato scritto il testo. { text } oppure { text: null } per ometterlo
skill.prompt Il testo di una skill viene espanso per Claude { text }
attribution.text Claude Code compone il testo di attribuzione di un commit o di una pull request { text }

Comandi e configurazione

Gli eventi dei comandi e della configurazione si attivano quando un comando viene eseguito o elencato e quando una riga di /config viene mostrata o modificata:

Evento Si attiva quando Un hook può restituire
command.run Un comando sta per essere eseguito { text }, {} oppure next(e)
command.describe Una volta per ogni comando, per l'elenco dei comandi { description, argumentHint, isHidden }
config.set Una riga di /config sta per cambiare next({ ...e, value }) oppure { deny: reason }
config.describe Una volta per ogni riga di /config { label, description, isHidden }

Turni

Gli eventi dei turni seguono una risposta dall'inizio alla fine, inclusa ogni richiesta al modello al suo interno:

Evento Si attiva quando Un hook può restituire
turn.start Inizia un turno next(e)
turn.step Una richiesta sta per essere inviata al modello yield* next(e), oppure next({ ...e, model }), next({ ...e, effort })
turn.complete Un turno è terminato next(e) oppure { text } per mostrare una riga sotto la risposta

Sessione

Gli eventi della sessione segnano l'avvio, la fine e la compattazione della sessione e lo scambio di messaggi con altre sessioni:

Evento Si attiva quando Un hook può restituire
session.start Una volta per ogni mod caricato, prima del primo prompt, e di nuovo dopo un ricaricamento di quel mod. Non dopo /clear, /resume o /branch. next(e)
session.end La sessione termina, oppure viene eseguito /clear, /resume o /branch. e.reason è clear, resume, logout, prompt_input_exit o other. /branch riporta resume. next(e)
session.compact La conversazione sta per essere compattata { skip: reason }
session.receive, session.send Un messaggio arriva da un altro agente o da un'altra sessione, o sta per esservi inviato. Consulta Inviare e ricevere messaggi tra sessioni. { consumed: reason } per receive, { isDelivered: false, reason } per send
session.append Una volta per ogni riga che la conversazione conserva, come un prompt, un blocco di risposta, il risultato di uno strumento o un avviso, prima che venga memorizzata next({ ...e, message }) per riscrivere il content della riga
session.attach, session.detach Un'altra app si connette alla sessione o si disconnette da essa next(e)
session.measure Dopo ogni turno e quando cambia la percentuale utilizzata di un limite del piano next(e)

Subagent

Gli eventi dei subagent si attivano quando un tipo di subagent viene offerto a Claude e quando un subagent sta per avviarsi:

Evento Si attiva quando Un hook può restituire
agent.offer Un tipo di subagent viene offerto a Claude { isOffered: false } per non renderlo disponibile
agent.spawn Un subagent sta per avviarsi { model } oppure { deny: reason }

Interfaccia

Gli eventi dell'interfaccia si attivano quando Claude Code disegna un punto di rendering e quando l'utente usa un controllo disegnato da un mod. Disegnare nell'interfaccia mostra cosa restituisce un hook ui.render:

Evento Si attiva quando
ui.render Un punto di rendering sta per essere disegnato
ui.resolve I mod vengono caricati, una volta per ogni app, punto di rendering e mod. Il risultato è la tabella degli elementi letta da $.ui.resolve(e).
ui.press, ui.input, ui.select Viene usato un Button, un Input o un Select disegnato da un mod
ui.focus, ui.scroll Il controllo con il focus o la posizione di scorrimento di un pannello o della banda sta per cambiare
ui.close Un pannello sta per chiudersi. e.id è il pannello e e.origin.kind è plugin, person o unload.
ui.message Un elemento Client invia dati al proprio mod

Altri mod

Questi eventi consentono a un mod di agire sugli altri mod mentre vengono caricati, per rifiutarne uno o modificare l'API dei mod che riceve:

Evento Si attiva quando Un hook può restituire
plugin.register Un modulo degli hook sta per essere caricato. e.uses elenca i suoi eventi, le chiamate all'API dei mod, le variabili d'ambiente e lo stato, così come li stampa claude plugin validate. Ogni chiamata è scritta senza il prefisso $., ad esempio fs.read. { refuse: reason }
engine.create L'API dei mod viene costruita per questo mod Un'API dei mod modificata, per aggiungere un namespace o escluderne uno

Telemetria

Gli eventi di telemetria si attivano per i record di utilizzo che Claude Code registra nei log:

Evento Si attiva quando Un hook può restituire
telemetry.log, telemetry.mark Un record di telemetria sta per essere registrato nei log, oppure viene contrassegnato un utilizzo di una funzionalità. In un mod che installi, assegna a un hook di telemetria il filtro { to: 'collector' }, come in on('telemetry.log', { to: 'collector' }, hook). Senza il filtro, il mod non supera claude plugin validate. * non corrisponde a questi eventi. next(e) oppure { deny: reason }

Eventi degli hook delle impostazioni

Ogni evento degli hook delle impostazioni è un evento denominato classic.<Event>, come classic.Stop o classic.PostToolUse. e è il JSON dello stdin dell'hook.

Chiamate all'API dei mod

Ogni metodo dell'API dei mod è anche un evento, denominato in base al suo namespace e al metodo, come fs.read, model.complete o ui.open. Un hook su uno di essi intercetta le chiamate provenienti dai mod eseguiti dopo di esso e può restituire next(e), { deny: reason } oppure { value }.

Metodi dell'API dei mod

L'API dei mod è l'argomento $ che ogni hook riceve. I suoi metodi sono raggruppati in namespace, come $.ui. Questa tabella elenca i metodi di ogni namespace per nome, quindi open nella riga $.ui corrisponde alla chiamata $.ui.open(...). Le guide mostrano l'uso di quelli più comuni, e i tipi per la tua build documentano ogni metodo con un esempio.

Namespace Metodi
$.plugin name, root: il nome e la directory di questo plugin
$.ui resolve, invalidate, open, close, panes, focus, scroll, toast, status, log, notice, ask, copy, blit
$.command register, run, list
$.tool register, call, check, list
$.agent register, spawn, list
$.model complete, fork, classify
$.prompt submit, read, fill, suggest, compose. Claude legge il testo di submit({ text }) dopo una frase che indica il tuo mod come mittente. submit({ text, asUser: true }) invia il testo come parole dell'utente stesso, senza quella frase.
$.turn abort
$.session messages, cwd, root, model, turns, id, repo, surfaces, usage, version, compact, send, append, authorize. usage() restituisce { startedAt, context, rateLimits, cost }: context contiene tokens, window e percent, e rateLimits è un elenco di { kind, percentUsed, resetsAt }.
$.config list, set
$.settings read
$.env get, set
$.fs read, write, list, exists, stat, ancestors. write non è atomico: sostituisce il contenuto del file sul posto, quindi un altro processo può leggere un file scritto solo in parte. Conserva in $.store i dati modificati da più sessioni.
$.store get, set, delete, keys. Un archivio chiave-valore condiviso da tutte le sessioni sulla macchina. Consulta Salvare da più di una sessione.
$.state Stato reattivo: get, set, con gli helper atom, read, update, derive e memberOf importati da claude-code
$.clock now, sleep, after, every
$.http fetch
$.process run, spawn
$.mcp call, connect. connect(server) connette un server MCP elencato nel manifest del tuo plugin.
$.audio play, speak
$.telemetry log, mark. Un record viene inviato solo quando la chiamata è effettuata da Claude Code o da un mod integrato.

Punti di rendering

Un punto di rendering è un punto di estensione nell'interfaccia di Claude Code. Ogni riga è un valore di e.component in un hook ui.render, con i campi di e.props e le app che lo visualizzano. e.surface è terminal o desktop. Modificare ciò che Claude Code disegna già mostra cosa può fare un hook in un punto, con un esempio per ciascuna scelta.

Punto e.props e.requestId Visualizzato su
Pane title, isFocused, bodyColumns, placement, scroll, view L'id del pannello Terminale, Desktop
AbovePrompt hasSurvey, isWorking, maxRows, bodyColumns, scroll, view Una sola istanza Terminale, Desktop
UserMessage text, origin, isExpanded e task o from a seconda dell'origine L'id del messaggio Terminale, Desktop
AssistantMessage Il testo della risposta L'id del messaggio Terminale, Desktop
ToolUse, ToolResult, ToolGroup Il nome, l'input e il risultato dello strumento L'id della chiamata allo strumento Terminale, Desktop
CommandOutput command, text L'id del messaggio Terminale, Desktop
AskUserQuestion La domanda e le opzioni L'id della chiamata allo strumento Terminale, Desktop
ToolProgress kind L'id della chiamata allo strumento Terminale
Spinner word, message, suffix, mode L'id dell'agente Terminale, Desktop
TurnDuration word, durationMs L'id del messaggio Terminale
InfoNotice text, command L'id del messaggio Terminale
SessionMode modes Una sola istanza Terminale, Desktop
PromptHint isDraft, isWorking, hint Una sola istanza Terminale, Desktop

e.viewport contiene columns, rows e isFullscreen. È assente finché l'app non ha misurato la propria finestra. Il suo rows è l'altezza dell'intera finestra, non del tuo pannello.

Per adattare un albero al suo punto, leggi queste prop nell'hook:

  • Larghezza di un Pane o della fascia: disegna fino a e.props.bodyColumns
  • Altezza di un Pane accanto alla trascrizione: quando e.props.placement è 'dock', e.props.scroll.bodyRows è il numero di righe di cui dispone il pannello
  • Altezza di un Pane sopra il prompt: quando e.props.placement è 'inline', il pannello cresce insieme al tuo albero fino a un limite, e bodyRows conta solo le righe visualizzate in quel momento. Il campo rows di $.ui.open richiede un limite diverso.

Un albero più alto del pannello scorre nel suo insieme.

Elementi

Gli elementi sono i componenti di base di un albero restituito da un hook ui.render, e li ottieni da $.ui.resolve(e). Crea un albero a partire dagli elementi mostra quelli più comuni insieme a come il terminale li disegna, e la galleria dell'interfaccia contiene screenshot della maggior parte di essi. Un segno di spunta indica che l'app può disegnare l'elemento.

Elemento Prop principali Terminale Desktop
Box key, layout flex, gap, padding, margin, width, height, borderStyle, backgroundColor, position, hover ✓ ✓
Text color, backgroundColor, bold, italic, underline, dimColor, inverse, wrap ✓ ✓
Button key, label, onPress, hotkey, plain, dimColor, autoFocus, action ✓ ✓
Link href, label ✓ ✓
Code Il codice, fino a 10.000 caratteri ✓ ✓
Markdown text, fino a 10.000 caratteri, key, dimColor, onLinkPress, pressableLinks ✓ ✓
Input key, label, placeholder, value, submitLabel, onSubmit, onInput, autoFocus ✓ ✓
Select key, label, options, value, onSelect, autoFocus ✓ ✓
Svg Un documento SVG, fino a 131.072 caratteri ✓
Client module, key ✓ ✓
Raster key, columns fino a 512, rows fino a 256, cells. Consulta Disegna una griglia di celle colorate. ✓
Image Byte PNG o RGBA fino a 2 MiB, oppure un percorso di file ✓

Altre regole per Button: action indica una delle scorciatoie da tastiera di Claude Code, e la combinazione assegnata dall'utente a quell'azione preme il pulsante quando si tratta di un accordo o di un tasto con modificatore. Un hotkey numerico su un pulsante nella banda si attiva anche quando l'utente digita solo quella cifra in un prompt vuoto e si ferma. Quando due pulsanti nello stesso disegno indicano lo stesso hotkey, lo ottiene quello successivo. autoFocus accetta solo true su qualsiasi controllo, quindi ometti la prop per lasciarlo disattivato.

Limiti

Gli hook e le chiamate all'API dei mod sono soggetti a limiti di tempo e di dimensione. Claude Code salta un hook che supera un limite di tempo e rifiuta una chiamata che supera un limite di dimensione.

Limite Valore
Il tempo di esecuzione proprio di un hook per un evento, senza contare il tempo trascorso dentro next o in una chiamata all'API dei mod diversa da $.clock.sleep 10 secondi
Il tempo di esecuzione di un gestore .catch 1 secondo
Tutti gli hook session.end insieme 1,5 secondi
Timeout di $.process.run 30 secondi per impostazione predefinita, 10 minuti al massimo
maxTokens di $.model.complete 1024 per impostazione predefinita, fino a 64.000 o al limite di output del modello
$.fs.read e $.fs.write 4 MiB per un singolo file
Un singolo figlio stringa di un Text 10.000 caratteri
$.store 4 MiB di JSON in totale
$.session.messages() Le 4.096 voci più recenti
Ridisegni di $.ui.invalidate('ui.render') Limitati a 10 al secondo, o 30 nel terminale per il riquadro visibile, la fascia espansa e la riga di suggerimento sotto il prompt. Le chiamate che arrivano prima vengono accorpate.
$.ui.toast Mostrato per 4 secondi, a meno che tu non passi { timeoutMs }
Un riquadro aperto senza che l'utente lo abbia richiesto Posizionato a partire da 144 colonne del terminale, 110 dopo che l'utente lo ha aperto una volta
Nomi di comandi, strumenti, tipi di subagent e riquadri Lettere, cifre, _ e -, fino a 64 caratteri
Un singolo test di claude plugin test 5 secondi, a meno che il test non imposti timeoutMs

Impostazioni e variabili d'ambiente

Queste sono le impostazioni e le variabili d'ambiente che influiscono sui mod. La colonna Dove indica da quale file di impostazioni o ambiente viene letta ciascuna:

Nome Dove Cosa fa
CLAUDE_CODE_PLUGIN_DIRS Ambiente, oppure env in ~/.claude/settings.json Directory di plugin da caricare come fa --plugin-dir, per le app a cui non puoi passare un flag. Percorsi assoluti separati da :, oppure da ; su Windows.
CLAUDE_CODE_PLUGIN_DIR_WATCH Ambiente 1 fa sì che una sessione non interattiva di lunga durata ricarichi i mod di --plugin-dir al salvataggio
prependPlugins, appendPlugins Impostazioni gestite. Impostazioni utente solo su una macchina senza impostazioni gestite, per un utente che non ha effettuato l'accesso con un piano Team o Enterprise. Elenchi di id di plugin, come acme-guard@acme-tools. I mod in prependPlugins vengono eseguiti prima di ogni mod installato da un utente, e i mod in appendPlugins vengono eseguiti dopo, nell'ordine elencato. Consulta L'ordine in cui vengono eseguiti i mod.
allowManagedModsOnly Impostazioni gestite, come opzione della protezione integrata Vengono caricati solo i mod che contano come quelli della tua organizzazione e i mod integrati in Claude Code. Gli hook delle impostazioni degli utenti continuano a essere eseguiti.
allowModsToOverrideDenyRules Impostazioni gestite, come opzione della protezione integrata Consente a un mod installato da un utente di approvare una chiamata a uno strumento che una regola deny rifiuta
allowManagedHooksOnly Impostazioni gestite Blocca gli hook e i mod installati che non appartengono alla tua organizzazione. Consulta cosa continua a essere eseguito.
disableAllHooks Qualsiasi file di impostazioni Nelle impostazioni gestite, non viene eseguito alcun mod o hook di un plugin installato. Nelle tue impostazioni, ciò che la tua organizzazione gestisce continua a essere eseguito. Consulta disableAllHooks.
disableSideloadFlags Impostazioni gestite Rifiuta --plugin-dir e --plugin-url all'avvio
pluginConfigs Impostazioni utente o gestite Contiene i valori di userConfig per un mod, indicizzati in base all'id del plugin, come acme-guard@acme-tools, oppure in base al suo nome seguito da @inline, come first-mod@inline, per un mod caricato con --plugin-dir

sec-default@builtin è una protezione integrata in Claude Code, elencata come cc-plugin-sec-default in /plugin e nel log di debug. Viene caricata prima di ogni mod installato da una persona su una macchina con impostazioni gestite, oppure per un utente che ha effettuato l'accesso con un piano Team o Enterprise. Se è impostato prependPlugins nelle impostazioni gestite, la protezione viene caricata solo quando quell'elenco la nomina, nella posizione indicata. Il suo codice sorgente si trova nella directory mods/sec-default del repository di Claude Code.

Comandi

Questi comandi e flag caricano, ispezionano e testano un mod. I comandi claude vengono eseguiti nella tua shell e i comandi / nel prompt di Claude Code. Nella tabella, <directory> indica un percorso che digiti, come in claude plugin validate ./first-mod. Le parentesi quadre indicano un argomento facoltativo.

Comando Cosa fa
/plugin Mostra una riga come 1 mod active · first-mod sotto le sue schede quando è stato caricato un mod non integrato
claude plugin validate <directory> Legge il manifest e il modulo degli hook di un plugin e segnala gli errori, gli eventi che gestisce e le chiamate all'API dei mod che effettua. --strict tratta gli avvisi come errori e --json stampa un report leggibile da una macchina.
claude plugin test [directory] Esegue ogni file nella directory, o nella directory corrente se non ne specifichi una, il cui nome termina con .test.ts o .test.tsx. Termina con stato 1 quando un test fallisce.
claude --plugin-dir <directory> Carica una directory di plugin per una sessione e ricarica il suo modulo degli hook quando salvi. Ripeti il flag per caricarne diverse.
/reload-plugins Ricarica i plugin quando lo esegui