Creare un mod

• Chiedi a Claude di scriverlo: descrivi quello che vuoi in una sessione di Claude Code
• Scrivilo tu stesso: segui il tutorial per imparare come funziona il codice di un mod. Non hai bisogno di Node.js, di un bundler o di un passo di build, perché Claude Code carica i file .js e .ts direttamente.

​

Chiedi a Claude un mod

​

Usa il mod in altre sessioni

• In una sessione che avvii: nel tuo shell, esegui claude --plugin-dir ~/mods/git-branch
• Per altre persone: aggiungilo a un marketplace in modo che possano installarlo

​

Sessioni in cui un mod scritto da Claude non può caricarsi

• Nessuno è lì per approvare: la sessione non può mostrarti un prompt, come in un’esecuzione claude -p o in modalità dontAsk
• Lo spazio di lavoro non è affidabile: non hai accettato il prompt di fiducia per la directory
• I mod sono fermati: hai avviato con --safe-mode o --bare, hai impostato disableAllHooks, o le impostazioni gestite della tua organizzazione lo bloccano

​

Scrivi un mod tu stesso

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 hooks

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

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

• Osservare: l’hook session.start registra il comando e l’hook tool.call conta la chiamata e chiede un ridisegno. Entrambi restituiscono next(e), quindi la sessione inizia e il tool viene eseguito come al solito.
• Rispondere: l’hook command.run restituisce il suo risultato e non chiama mai next. Il secondo argomento a 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, quindi Claude Code disegna il suo spinner usuale con il tuo testo dopo la parola

​

Continua a lavorare su un mod

​

Cambia un mod con Claude

claude --plugin-dir ./first-mod

​

Ottieni le definizioni di tipo per la tua versione

​

Verifica cosa Claude Code legge dal tuo mod

claude plugin validate ./first-mod

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

✔ Validation passed

• Scrivi ogni chiamata all’API dei mod per intero: $, il namespace, quindi il metodo, come in $.store.get('notes'). Puoi passare $ a una funzione dichiarata al livello superiore dello stesso file, e per una tua funzione denominata loadNotes, la riga calls: legge quindi $.store.get (via loadNotes). Passare $ a un metodo, una funzione definita dentro l’hook, o una funzione che importi da un altro dei tuoi file non supera la convalida. Le funzioni read e update che $.state usa sono le importazioni che possono prenderlo. Non assegnare $ o uno dei suoi namespace a una variabile, destrutturarlo o 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 un letterale di stringa, come in '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.
• Dentro register, non dichiarare una seconda variabile o parametro denominato on. La convalida fallisce con "on" is declared again (shadowed).
• Importa solo da file dentro la directory del plugin, per percorso relativo. L’unica importazione nuda consentita è claude-code, per i tipi e alcuni helper.
• Usa dichiarazioni import in cima al 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 un modulo ES, con import e non require. Il riferimento elenca le estensioni di file che Claude Code carica.

​

Testa il mod

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' }))

  // Raise 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')
})

claude plugin test

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]

​

Condividi il tuo mod

​

Prossimi passi

• Disegna nell’interfaccia: apri un riquadro, disegna sopra il prompt e aggiungi pulsanti e campi di testo
• Reagisci agli eventi: aggancia le chiamate ai tool, i prompt e i turni
• Usa l’API dei mod: aggiungi comandi e tool, chiama un modello ed esegui lavoro su un timer
• Testa un mod: stub quello che Claude Code risponderebbe, 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 sorgente dei mod integrati: plugin completi, ciascuno con il suo modulo hooks e test