SpyBara
Go Premium

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

This page contains 326 additions and 0 deletions.

2026
Fri 2 10:01

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, con un link alla sezione della guida che lo spiega, quando esiste.

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, come 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 il cui nome termina in .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 nel manifest, con i valori predefiniti già inseriti.

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 elencato 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 viene interrotto 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 di esecuzione dei 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 è quello che resta ora
next.to(e, tier) Salta a un tier successivo, che è 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 forma abbreviata. next(e) passa l'evento invariato. 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 che Claude effettua, dalla descrizione che Claude legge 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 } o { 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 autonomamente a Claude, 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 }) o { drop: reason }
prompt.fill, prompt.suggest Un 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 esegue il rendering di 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 nelle definizioni, e.detail contiene i dati da cui è 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 }, {} o 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 }) o { 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 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 conservata dalla conversazione, 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 nasconderlo
agent.spawn Un subagent sta per avviarsi { model } o { 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, Input o Select disegnato da un mod
ui.focus, ui.scroll Il controllo con il focus o la posizione di scorrimento di un pannello o della fascia sta per cambiare
ui.close Un pannello sta per chiudersi. e.id è il pannello ed e.origin.kind è plugin, person o unload.
ui.message Un elemento Client invia dati al proprio mod

Altri mod

Questi eventi permettono a un mod di agire su 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 $., come 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:

Evento Si attiva quando Un hook può restituire
telemetry.log, telemetry.mark Un record di telemetria sta per essere registrato, oppure viene segnato 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) o { deny: reason }

Eventi degli hook delle impostazioni

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

Chiamate all'API dei mod

Ogni metodo dell'API dei mod è anche un evento, con il nome del suo namespace e metodo, come fs.read, model.complete o ui.open. Un hook su uno di essi intercetta le chiamate dei mod eseguiti dopo di lui e può restituire next(e), { deny: reason } o { 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 per nome i metodi di ogni namespace, quindi open nella riga $.ui corrisponde alla chiamata $.ui.open(...). Le guide mostrano l'uso di quelli più comuni, e le definizioni dei 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 ha 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 che più sessioni modificano.
$.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 ne eseguono il rendering. e.surface è terminal o desktop. Modificare ciò che Claude Code disegna già mostra cosa può fare un hook in un punto di rendering, con un esempio per ogni scelta.

Punto e.props e.requestId Reso su
Pane title, isFocused, bodyColumns, placement, scroll, view L'id del pannello Terminale, Desktop
AbovePrompt hasSurvey, isWorking, maxRows, bodyColumns, scroll, view Un'unica 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 Un'unica istanza Terminale, Desktop
PromptHint isDraft, isWorking, hint Un'unica 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 di rendering, leggi queste prop nell'hook:

  • Larghezza di un Pane o della fascia: disegna in base 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 visibili 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 mattoni di un albero restituito da un hook ui.render, e li ottieni da $.ui.resolve(e). Costruire un albero dagli elementi mostra quelli più comuni con il modo in cui 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 Disegnare 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 azioni delle scorciatoie da tastiera di Claude Code, e la combinazione dell'utente per quell'azione preme il pulsante quando si tratta di un accordo o di un tasto con modificatore. Un hotkey numerico su un pulsante nella fascia si attiva anche quando l'utente digita solo quella cifra in un prompt vuoto e fa una pausa. Quando due pulsanti nello stesso disegno indicano lo stesso hotkey, lo ottiene il secondo. autoFocus accetta solo true su qualsiasi controllo, quindi ometti la prop per lasciarlo disattivato.

Limiti

Gli hook e le chiamate all'API dei mod vengono eseguiti entro 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, escluso il tempo trascorso all'interno di next o di 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, al massimo 10 minuti
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 pannello 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 pannello aperto senza che l'utente lo abbia chiesto 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 pannelli 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 ; 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 dopo, nell'ordine elencato. Consulta L'ordine di esecuzione dei mod.
allowManagedModsOnly Impostazioni gestite, come opzione della protezione integrata Vengono caricati solo i mod che sono considerati 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 Permette a un mod installato da un utente di approvare una chiamata a uno strumento rifiutata da una regola deny
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 è gestito dalla tua organizzazione 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 per id del plugin, come acme-guard@acme-tools, oppure per il 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 gestito, la protezione viene caricata solo quando quell'elenco la indica, nella posizione elencata. 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 riporta 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 dalle macchine.
claude plugin test [directory] Esegue ogni file nella directory, o nella directory corrente se non ne indichi una, il cui nome termina in .test.ts o .test.tsx. Termina con stato 1 quando un test non riesce.
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 più di una.
/reload-plugins Ricarica i plugin quando lo esegui