Scrivi tre file:

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

• plugin.json: il manifest del plugin
• hooks.json: punta al tuo file di codice
• register.js: il tuo codice, chiamato modulo degli hook

mkdir -p first-mod/.claude-plugin first-mod/hooks

New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks

{
"name": "first-mod",
"version": "0.1.0",
"description": "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command",
"author": { "name": "Your Name" }
}

{
"description": "The first-mod hooks module",
"modules": ["./register.js"]
}

// The count, shared by the hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
// Runs when the session starts, before your first prompt
on('session.start', async ($, e, next) => {
// Add the /tally command
await $.command.register({
name: 'tally',
description: 'Show how many tool calls Claude has made',
})
// Let the session start as usual
return next(e)
})

// Runs each time Claude is about to use a tool
on('tool.call', async ($, e, next) => {
calls += 1
// Ask Claude Code to draw the interface again, so the new count shows
$.ui.invalidate('ui.render')
// Let the tool run as usual
return next(e)
})

// Runs when you type /tally, and only then, because of the matcher
on('command.run', { command: 'tally' }, async () => {
// The text to print in the transcript
return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }
})

// Runs each time Claude Code draws the spinner
on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
// Keep Claude Code's spinner, with the count added after its word
return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
})
}

claude --plugin-dir ./first-mod

claude -p "/tally" --plugin-dir ./first-mod

first-mod: Claude has made 0 tool calls since this mod loaded

// Runs each time Claude Code draws the spinner
on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
// Keep Claude Code's spinner, with the count added after its word
return next({ ...e, props: { ...e.props, suffix: ' · tools used: ' + calls + '…' } })
})

Come funziona il mod di esempio

Ogni funzione che passi a on è un hook, ovvero un gestore di eventi. Claude Code passa a ogni hook gli stessi tre argomenti:

• L'API dei mod, chiamata $: ogni metodo che un mod può chiamare per raggiungere l'esterno, organizzato in namespace come $.ui e $.command
• L'evento, chiamato e: l'input dell'evento come dati semplici, ad esempio il nome e gli argomenti di una chiamata a uno strumento
• Il gestore successivo, chiamato next: una funzione che passa l'evento agli altri mod e poi al comportamento proprio di Claude Code, e restituisce il risultato

Gli hook in first-mod gestiscono i loro eventi in questi modi:

• Osservare: l'hook session.start registra il comando e l'hook tool.call conta la chiamata e richiede un ridisegno. Entrambi restituiscono next(e), quindi la sessione si avvia e lo strumento viene eseguito come di consueto.
• Rispondere: l'hook command.run restituisce il proprio risultato e non chiama mai next. Il secondo argomento di on, { command: 'tally' }, è un filtro, chiamato matcher, quindi l'hook viene eseguito solo per /tally.
• Riscrivere: l'hook ui.render chiama next con una copia di e il cui suffix contiene il conteggio, così Claude Code disegna il suo consueto spinner con il tuo testo dopo la parola

Claude Code osserva una directory caricata con --plugin-dir e ricarica a caldo il modulo degli hook quando un file al suo interno cambia. Ogni ricaricamento esegue di nuovo register, quindi calls si azzera a 0 e /tally ricomincia a contare. Per mantenere un valore tra i ricaricamenti, consulta Mantieni lo stato.

Continua a lavorare su un mod

Una volta caricato un mod, puoi chiedere a Claude di modificarlo, verificare il tuo codice rispetto alle definizioni dei tipi per la tua versione, elencare gli eventi e le chiamate che Claude Code vi trova e testarlo.

Modifica un mod con Claude

Per modificare un mod che hai già, avvia la sessione con --plugin-dir che punta alla directory del mod, in modo che ciò che Claude scrive venga caricato nella stessa sessione:

claude --plugin-dir ./first-mod

Poi chiedi la modifica, ad esempio add a /tally-reset command to this mod that sets the tally back to zero. Claude modifica il modulo degli hook, esegue claude plugin validate e corregge ciò che viene segnalato. Una directory che carichi con --plugin-dir è un percorso protetto, quindi nelle modalità default e acceptEdits ti viene chiesto di approvare ogni modifica di Claude al mod. La tabella dei percorsi protetti indica il risultato per le altre modalità di permesso.

I file che Claude salva durante il suo turno vengono ricaricati al termine del turno, quindi puoi provare /tally-reset non appena Claude ha finito.

Ottieni le definizioni dei tipi per la tua versione

Ogni volta che Claude Code carica o ricarica un mod da una directory che passi a --plugin-dir, oppure un mod che Claude ha scritto per te, scrive dei file di dichiarazione TypeScript, con estensione .d.ts, in .claude-plugin/types/ all'interno della directory del mod. Questi descrivono esattamente gli eventi, i metodi dell'API dei mod e gli elementi presenti nella versione di Claude Code che stai eseguendo, così il tuo editor può completare automaticamente e verificare i tipi dei tuoi hook. Per consultare le dichiarazioni online, leggi mods/types/claude-code.d.ts nel repository di Claude Code, la cui prima riga indica la versione che lo ha scritto. La directory contiene questi file:

Se il tuo mod non ha un proprio tsconfig.json, Claude Code ne aggiunge uno nella radice del mod che estende quello generato, così il tuo editor e tsc -p ./first-mod verificano i tipi del mod senza ulteriore configurazione.

Gli eventi e i metodi possono cambiare da una release all'altra, quindi in caso di discrepanza fidati di questi file piuttosto che di qualsiasi pagina, inclusa questa.

claude-code/index.d.ts è il riferimento più completo per la tua build, con un commento e un esempio per ogni metodo dell'API dei mod. Per cercare qualcosa, cerca nel file il suo nome, ad esempio 'tool.call'.

Verifica cosa legge Claude Code dal tuo mod

Per vedere il tuo mod come lo vede Claude Code, senza eseguire il tuo codice né avviare una sessione, usa claude plugin validate. Il comando controlla il manifest ed esegue sul sorgente del modulo degli hook la stessa analisi statica che Claude Code esegue quando carica un mod. Nella tua shell, eseguilo sulla directory del mod:

claude plugin validate ./first-mod

Per first-mod, l'output include queste righe.

  ❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}
  ❯ ./register.js calls: $.command.register, $.ui.invalidate

✔ Validation passed

La riga hooks: elenca gli eventi a cui il tuo modulo si aggancia, ciascuno con il suo filtro tra parentesi graffe. La riga calls: elenca ogni metodo dell'API dei mod che chiama. Un modulo che legge o imposta variabili d'ambiente ottiene anche le righe env reads: e env writes:, e uno che usa $.state ottiene state reads: e state writes:.

Se un evento che intendevi gestire manca dalla prima riga, nemmeno Claude Code chiamerà quell'hook. La causa più comune è un nome di evento scritto in modo errato, che il comando segnala con un errore come "tool.calls" is not an event.

Segui queste regole affinché l'analisi statica possa trovare ogni hook e ogni chiamata:

• Scrivi ogni chiamata all'API dei mod per intero: $, il namespace, poi il metodo, come in $.store.get('notes'). Puoi passare $ a una funzione dichiarata al livello superiore dello stesso file e, per una tua funzione chiamata loadNotes, la riga calls: riporterà quindi $.store.get (via loadNotes). Passare $ a un metodo, a una funzione definita all'interno dell'hook o a una funzione che importi da un altro dei tuoi file non supera la validazione. Le funzioni read e update che $.state usa sono gli import che possono riceverlo. Non assegnare $ o uno dei suoi namespace a una variabile, non destrutturarlo e non indicizzarlo con un nome calcolato. const ui = $.ui fallisce con $.ui is used as a value.
• Scrivi il nome dell'evento in ogni chiamata on come stringa letterale, ad esempio 'tool.call'. Una variabile, o un ciclo su un elenco di nomi, fallisce con the event name passed to on() is not a string literal.
• All'interno di register, non dichiarare una seconda variabile o un secondo parametro chiamato on. La validazione fallisce con "on" is declared again (shadowed).
• Importa solo da file all'interno della directory del plugin, tramite percorso relativo. L'unico import senza percorso consentito è claude-code, per i tipi e alcune funzioni di supporto.
• Usa dichiarazioni import all'inizio del file, come in import { name } from './file.js'. Un import() dinamico fallisce con a dynamic import(); a hooks module imports its own files with an import declaration.
• Scrivi ogni file come modulo ES, con import e non require. Il riferimento elenca le estensioni di file che Claude Code carica.

Testa il mod

Puoi scrivere test automatizzati per un mod ed eseguirli dalla tua shell con claude plugin test, senza sessione, accesso o rete. Un test attiva gli eventi gestiti dai tuoi hook e verifica cosa hanno fatto gli hook.

Questo test attiva due chiamate agli strumenti, esegue /tally e verifica che la risposta le conti entrambe. Salvalo come first-mod/tests/first-mod.test.ts:

import { expect, test } from 'claude-code/testing'

test('/tally reports the tool calls the mod has seen', async ($, on) => {
  // Answer each tool call in Claude Code's place, so no tool runs
  on('tool.call', () => ({ result: 'ok' }))

  // Fire two tool calls, which the mod's tool.call hook counts
  await $.tool.call({ tool: 'Bash', command: 'ls' })
  await $.tool.call({ tool: 'Read', file_path: 'README.md' })

  // Run /tally and check the text its hook returns
  const answer = await $.command.run({ command: 'tally', args: '' })
  expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')
})

Nella tua shell, esegui i test dalla directory first-mod:

claude plugin test

L'output indica ogni test e se è stato superato, con tempi che variano da un'esecuzione all'altra:

tests/first-mod.test.ts:
(pass) /tally reports the tool calls the mod has seen [22.87ms]

 1 pass
 0 fail
Ran 1 test across 1 file. [0.19s]

Testa un mod spiega come simulare una chiamata al modello o lo store e come testare timer e disegni.

Condividi il tuo mod

Un mod è un plugin, quindi ne gestisci la versione nel manifest e le persone lo installano e lo aggiornano con i comandi /plugin. Il modo in cui lo condividi dipende da chi lo userà:

• Poche persone: invia loro la directory del plugin o un file .zip che la contiene. Consulta Condividere un plugin senza un marketplace
• Il tuo team: elencalo nel tuo marketplace, ad esempio un repository privato con una directory per ogni plugin. Per aggiungere quel marketplace per tutti coloro che lavorano in un repository, registralo nelle impostazioni del repository
• L'intera organizzazione: un amministratore può installare i mod della tua organizzazione tramite le impostazioni gestite
• Chiunque: rendi pubblico il repository del tuo marketplace, oppure invia il plugin alla directory di Anthropic

Prima di farlo, controlla il name del plugin: claude plugin validate rifiuta un nome che sembra uno di quelli di Anthropic, come uno che inizia con claude-. Gli eventi e i metodi possono cambiare tra una release e l'altra, quindi il tuo README è il posto giusto per indicare con quale versione di Claude Code l'hai testato.

Continua a sviluppare sulla directory con --plugin-dir, non su una copia installata. Claude Code memorizza nella cache un plugin installato in base alla versione, quindi le tue modifiche non raggiungono la copia installata finché non incrementi la versione e lo installi di nuovo.

Passaggi successivi

• Disegna nell'interfaccia: apri un riquadro, disegna sopra il prompt e aggiungi pulsanti e campi di testo
• Reagisci agli eventi: intercetta le chiamate agli strumenti, i prompt e i turni
• Usa l'API dei mod: aggiungi comandi e strumenti, chiama un modello ed esegui operazioni a intervalli regolari
• Testa un mod: simula le risposte di Claude Code e testa timer e disegni
• Risolvi i problemi di un mod: i motivi per cui un mod non fa nulla e il log di debug
• Leggi il codice sorgente dei mod integrati: plugin completi, ciascuno con il proprio modulo degli hook e i propri test