SpyBara
Go Premium

plugins/mods/reference.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 105 additions and 97 deletions.

2026
Fri 2 22:59 Sat 3 23:57 Sun 4 23:58 Tue 6 23:59 Wed 7 23:59 Thu 8 22:58 Fri 9 23:02 Sat 10 23:01 Sun 11 23:57 Wed 14 22:58 Thu 15 23:58 Fri 16 22:59 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Mon 26 22:57 Tue 27 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. Le voci coprono la CLI di Claude Code e l'app Desktop a partire dalla v2.1.290, e l'estensione VS Code a partire dalla v2.1.299. Ogni voce riporta il nome e una descrizione di una riga e, dove presente, rimanda alla sezione della guida che lo spiega.

[!NOTE]

Il riferimento completo sono le dichiarazioni TypeScript per i mod di Claude Code, che descrivono ogni evento, metodo ed elemento, con esempi. La copia su GitHub può essere più vecchia della versione di Claude Code che hai installato. Quando le due non coincidono, fai affidamento sulla copia che Claude Code scrive per la tua versione.

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 Solo in un gestore .catch. kind è throw o timeout quando l'hook non è riuscito, e message è il testo dell'errore. kind è re-entry quando l'hook è stato saltato perché l'evento proveniva dall'interno di una chiamata all'API dei mod effettuata da quell'hook o dal codice del tuo mod al di fuori dei suoi hook. re-entry richiede Claude Code v2.1.292 o versioni successive.
next.error.cause Impostato solo quando kind è re-entry. rewritten se un hook tool.call o PreToolUse ha modificato la chiamata all'API dei mod da cui proveniva l'evento, oppure se un hook agent.spawn ha modificato un agente avviato da quella chiamata. lent quando a generare quell'evento è stato un metodo che un altro mod aggiunge all'API dei mod, a meno che non si applichi anche rewritten. lent richiede Claude Code v2.1.292 o versioni successive e rewritten v2.1.300 o versioni successive.
next.called Solo in un gestore .catch. true quando l'hook 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. next(e) oppure { decision }, con decision impostato su allow, ask o deny e un reason facoltativo
tool.describe Una volta per ogni strumento, quando la sua descrizione viene inviata per la prima volta a Claude. Una seconda volta per uno strumento MCP quando Claude lo carica tramite la ricerca degli strumenti, con e.description impostato sul testo che Claude legge per lo strumento caricato. { description }, facoltativamente con isDeferred impostato su true per mettere lo strumento dietro la ricerca degli strumenti o su false per caricarlo subito

Campi dell'agente e dell'organizzazione su tool.check

In un hook tool.check, leggi questi campi per distinguere la chiamata di un subagent da quella della conversazione principale e per verificare se la tua organizzazione richiede l'approvazione per uno strumento di un connettore:

Su tool.check, e.agentId e e.ceiling richiedono Claude Code v2.1.290 o versioni successive.

Il campo e.isReadOnly su tool.check

In un hook tool.check, e.isReadOnly è true quando lo strumento segnala questa chiamata come di sola lettura. Altrimenti il campo è assente, non false. Il valore è ciò che segnala lo strumento stesso, quindi leggi Verificare se una chiamata a uno strumento è di sola lettura prima di approvare una chiamata basandoti solo su questo campo.

Su tool.check, e.isReadOnly richiede Claude Code v2.1.304 o versioni successive.

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.autocomplete L'utente digita nella casella del prompt e una parola termina in corrispondenza del cursore. e.token è quella parola. Claude Code non attende l'hook: le sue righe di completamento automatico vengono mostrate per prime. { suggestions }, un elenco di righe { text, label, description } mostrate sotto quelle di Claude Code. La scelta di una riga sostituisce la parola con il suo text.
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
prompt.mention Claude Code sta per leggere un file menzionato con @ in un prompt. Richiede Claude Code v2.1.290 o versioni successive. next({ ...e, path }) per leggere un file diverso, oppure { deny: reason }
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 }

Campi di origine e frontmatter su skill.prompt

In un hook skill.prompt, puoi leggere questi campi insieme al nome della skill in e.skill e al testo che Claude legge in e.text:

Campo Tipo Cosa contiene
e.source string Chi fornisce la skill: policySettings, userSettings o projectSettings per una skill rispettivamente nella posizione enterprise, personale o di progetto. Le altre origini restituiscono una parola come plugin, mcp, syncedSkills o built-in.
e.pluginName string Il nome del plugin, per una skill il cui e.source è plugin
e.path string Il percorso assoluto del file SKILL.md della skill, o del suo file .md per una skill scritta come file di comando. Assente quando la skill non ha alcun file su questa macchina, come nel caso di una skill integrata.
e.frontmatter object Il frontmatter del file della skill, come dati semplici
e.frontmatterProblem string Il motivo per cui in e.frontmatter manca il frontmatter del file o una delle sue chiavi, come in is a list or a single value, not a table. Assente quando e.frontmatter contiene l'intero frontmatter o quando la skill non ne ha.

Un hook può passare un text o un frontmatter modificato a next: gli hook successivi leggono entrambi e Claude legge il text finale. Un hook che modifica qualsiasi altro campo non riesce.

Su skill.prompt, e.source, e.pluginName, e.path, e.frontmatter e e.frontmatterProblem richiedono Claude Code v2.1.299 o versioni successive.

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 }) con un message.content modificato, per riscrivere i blocchi di testo della riga o il content di un blocco tool_result al suo interno
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 o un membro di un team di agenti 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 o un membro di un team di agenti sta per avviarsi. Per un membro del team, e.isTeammate è true. next({ ...e, model }) per sceglierne il modello, oppure { deny: reason }

Quando Claude riprende un subagent con lo strumento SendMessage, il tuo hook agent.spawn non viene eseguito di nuovo. Per rifiutare le chiamate a SendMessage che riprendono un subagent, individua quello strumento in un hook tool.call.

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
ui.fault Un elemento Client disegnato dal tuo mod non è riuscito a caricarsi, a essere disegnato o a essere eseguito. e.phase è load, render o run, e e.reason è il messaggio di errore. Richiede Claude Code v2.1.289 o versioni successive.

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. Un mod al di fuori del livello user può anche escluderne uno.

Quando l'hook di un altro mod chiama un metodo su un namespace che hai aggiunto in engine.create, le chiamate $ del tuo metodo vengono eseguite nel contesto di quell'hook finché ogni hook su quell'evento non ha restituito un risultato. Ad esempio, un percorso relativo viene risolto rispetto alla directory di lavoro di quell'hook, e $.prompt.submit viene rifiutata mentre il turno è in attesa di quell'hook. Le chiamate che il tuo metodo effettua dopo quel momento vengono eseguite nel contesto proprio del tuo mod.

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, notify, status, log, notice, ask, copy, selection, blit
$.command register, run, list
$.tool register, call, check, list
$.agent register, spawn, list. list() restituisce i subagent e i compagni di squadra di questa sessione, ciascuno con uno status tra pending, running, waiting, idle, completed, failed o killed, dove idle e waiting richiedono Claude Code v2.1.289 o versioni successive.
$.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 indica l'app che sta disegnando, come terminal, desktop o vscode. Modificare ciò che Claude Code disegna già mostra cosa può fare un hook in un punto, con un esempio per ciascuna scelta.

Il rendering nell'estensione VS Code richiede la versione 2.1.299 o successiva dell'estensione. Una sessione che non recupera i feature flag richiede la versione 2.1.304 o successiva. Disegnare nell'estensione VS Code elenca ciò che l'estensione disegna in modo diverso.

Punto e.props e.requestId Visualizzato su
Pane title, isFocused, bodyColumns, placement, scroll, view L'id del pannello Terminale, Desktop, VS Code
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, VS Code
AssistantMessage Il testo della risposta L'id del messaggio Terminale, Desktop, VS Code
ToolUse, ToolResult, ToolGroup Il nome, l'input e il risultato dello strumento L'id della chiamata allo strumento Terminale, Desktop, VS Code
CommandOutput command, text L'id del messaggio Terminale, Desktop
AskUserQuestion La domanda e le opzioni L'id della chiamata allo strumento Terminale, Desktop, VS Code
ToolProgress kind L'id della chiamata allo strumento Terminale
Spinner word, message, suffix, mode L'id dell'agente Terminale, Desktop, VS Code
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. Nel terminale e nell'app Desktop, è assente finché l'app non ha misurato la propria finestra. Lì, il suo rows è l'altezza dell'intera finestra, non del tuo pannello. Nell'estensione VS Code, è sempre presente.

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 per il tuo albero
  • 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 è quel limite. Per richiedere un limite diverso, consulta il campo rows di $.ui.open.

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 VS Code
Box key, layout flex, gap, padding, margin, width, height, minWidth, minHeight, borderStyle, borderColor, borderDimColor, backgroundColor, position, top, left, right, bottom, overflow, display, hover ✓ ✓ ✓
Text color, backgroundColor, bold, italic, underline, strikethrough, dimColor, inverse, wrap, size, weight, mono, tabular, hover ✓ ✓ ✓
Button key, label, onPress, hotkey, plain, dimColor, autoFocus, action, hover ✓ ✓ ✓
Link href, label. Consulta Limiti. ✓ ✓ ✓
Code source, language, path, startLine, format, wrap ✓ ✓ ✓
Markdown text, key, dimColor, onLinkPress, pressableLinks ✓ ✓ ✓
Input key, label, placeholder, value, submitLabel, onSubmit, onInput, autoFocus ✓ ✓ ✓
Select key, label, options, value, onSelect, autoFocus ✓ ✓ ✓
Svg una source di markup SVG fino a 131.072 caratteri, testo alt, width, height e isInteractive ✓ ✓
Client module, key, props, width, height, flexGrow ✓ ✓
Raster key, columns fino a 512, rows fino a 256, cells. Consulta Disegna una griglia di celle colorate. ✓
Image key, una source come byte PNG o RGBA fino a 2 MiB, oppure un percorso di file, columns e rows fino a 255, e testo alt. Consulta quali terminali lo disegnano. ✓

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
  • Hotkey numerici nella banda: 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
  • Una banda compressa: mentre la banda è compressa, né una combinazione action né un hotkey premono un pulsante al suo interno
  • Due pulsanti sullo stesso hotkey: 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.

L'estensione VS Code ignora alcune prop degli elementi e disegna l'elemento come se le avessi omesse:

  • Box: position con i relativi top, left, right e bottom, alignSelf, borderDimColor e hover
  • Text: size, mono, tabular e hover
  • Button: hotkey, plain, autoFocus, action e hover, quindi lì l'utente preme un pulsante con un clic, oppure con Invio quando ha il focus
  • Code: language, path, startLine, format e wrap, quindi il codice viene disegnato senza colori né numeri di riga, e un blocco format: 'diff' mostra il testo grezzo del diff
  • Input e Select: autoFocus
  • Svg: isInteractive

Stili del bordo di Box

Per disegnare un bordo attorno a un Box, imposta la sua borderStyle su uno di questi nomi, come in borderStyle: 'round'. Ogni riga indica cosa disegna il terminale per quel nome e mostra il bordo superiore.

borderStyle Cosa disegna il terminale Bordo superiore
'single' Linee sottili con angoli squadrati ┌──┐
'double' Linee doppie ╔══╗
'round' Linee sottili con angoli arrotondati ╭──╮
'bold' Linee spesse ┏━━┓
'singleDouble' Linee sottili in alto e in basso, linee doppie sui lati ╓──╖
'doubleSingle' Linee doppie in alto e in basso, linee sottili sui lati ╒══╕
'classic' I caratteri ASCII +, - e | +--+
'arrow' Frecce che puntano verso l'interno del Box ↘↓↓↙
'dashed' Linee tratteggiate con angoli vuoti ╌╌
'quote' Una barra, ▎, lungo il lato sinistro e celle vuote sugli altri tre lati Vuoto

Un Box la cui borderStyle indica qualsiasi altro nome, come 'rounded', viene disegnato senza bordo.

Passi di spaziatura di Box

Le prop di spaziatura di Box sono gap, columnGap, rowGap, padding, margin e le forme di padding e margin per un solo lato o un solo asse, come paddingX e marginTop. Ognuna accetta un numero di celle del terminale, come gap: 1, oppure il nome di un passo, come gap: 'md'. Nel terminale e nell'estensione VS Code, ogni passo corrisponde a questo numero di celle:

Passo Celle in orizzontale Celle in verticale
'xs' 1 0
'sm' 1 0
'md' 2 1
'lg' 3 1
'xl' 4 2

Se imposti gap, padding o margin su un passo, il passo si applica contemporaneamente in orizzontale e in verticale. Ad esempio, nel terminale e nell'estensione VS Code, padding: 'md' corrisponde a due celle su ciascun lato e a una riga sopra e sotto.

I nomi dei passi richiedono Claude Code v2.1.299 o successivo. Su una release precedente, Claude Code disegna la propria versione del sito al posto di un albero che usa il nome di un passo.

Prop tipografiche di Text

Imposta size, weight, mono o tabular su un Text per chiedere all'app che disegna il tuo albero una dimensione del testo, uno spessore, un carattere a spaziatura fissa o cifre di larghezza uguale. Prima di fare affidamento su una prop, verifica cosa ne fanno il terminale e l'estensione VS Code. Se un'app ignora una prop che hai impostato, il tuo albero viene comunque disegnato, con il testo come se avessi omesso quella prop.

Prop Valori Nel terminale Nell'estensione VS Code
size 'caption', 'footnote', 'body', 'heading' o 'title' Ignorata: il terminale ha una sola dimensione del testo Ignorata
weight 'regular', 'medium', 'semibold' o 'bold' semibold e bold vengono disegnati come testo in grassetto semibold e bold vengono disegnati come testo in grassetto
mono true per chiedere il carattere a spaziatura fissa dell'app Ignorata: il terminale è sempre a spaziatura fissa Ignorata, quindi il testo mantiene il carattere proprio dell'estensione
tabular true per chiedere cifre di larghezza uguale, in modo che un numero che si aggiorna sul posto o una colonna di numeri restino allineati Ignorata: le cifre del terminale occupano già una cella ciascuna Ignorata

Queste quattro prop richiedono Claude Code v2.1.299 o successivo. Su una release precedente, Claude Code disegna la propria versione del sito al posto di un albero che imposta size, weight, mono o tabular.

Sostituisci bold con weight

bold su un Text è deprecato in favore di weight e funziona ancora. Per sostituirlo su un Text senza weight, cambia bold: true in weight: 'semibold' per ottenere lo stesso risultato su Claude Code v2.1.299 o successivo.

Su una release precedente alla v2.1.299, un albero che imposta weight non viene disegnato e Claude Code disegna invece la propria versione del sito. Se imposti sia bold sia weight su un Text, bold non ha alcun effetto.

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.

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, o 50 millisecondi per un hook prompt.edit
Il tempo di esecuzione di un gestore .catch 1 secondo
Tutti gli hook session.end insieme Quanto il budget dell'hook SessionEnd, 1,5 secondi a meno che tu non lo modifichi, contati da quando terminano gli hook SessionEnd delle tue impostazioni
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
Il corpo di una richiesta $.http.fetch 4 MiB, contati in caratteri. Una chiamata con un corpo più grande viene rifiutata.
Il corpo di una risposta $.http.fetch 4 MiB. text contiene i primi 4 MiB e il resto non viene letto. Quando l'header Content-Length dichiara una dimensione maggiore, la chiamata viene invece rifiutata, con un motivo che termina con is over the 4194304-byte limit, tranne quando l'ultima richiesta dopo eventuali reindirizzamenti usa il metodo HEAD. L'esenzione per HEAD richiede Claude Code v2.1.296 o versioni successive.
Una singola chiamata $.http.fetch, reindirizzamenti e corpo inclusi 30 secondi
Reindirizzamenti seguiti da una singola chiamata $.http.fetch 5
Il motivo drop di un hook o il motivo deny di config.set 4.096 caratteri. La parte finale di un motivo più lungo viene troncata, e il drop o il deny si applica comunque. Il troncamento richiede Claude Code v2.1.292 o versioni successive; nelle versioni precedenti l'hook invece non riesce.
Testo in un singolo albero Vengono disegnati i primi 100.000 caratteri
Il language o il path di un Code, il value di un'opzione Select o il module di un Client 10.000 caratteri. Se uno è più lungo, Claude Code disegna la propria versione del sito.
L'href di un Link 2.048 caratteri. Un href più lungo impedisce il disegno dell'intero albero.
$.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
Scope, come funzioni, blocchi e cicli, annidati l'uno dentro l'altro in un singolo file di un modulo degli hook 2.000
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, in una sessione la cui credenziale non è un /login 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 Solo i mod che contano come quelli della tua organizzazione e i mod integrati in Claude Code eseguono i propri hook. 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 in una sessione la cui credenziale è un /login 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