Crear un mod

• Pida a Claude que lo escriba: describa lo que desea en una sesión de Claude Code
• Escríbalo usted mismo: siga el tutorial para aprender cómo funciona el código de un mod. No necesita Node.js, un empaquetador o un paso de compilación, porque Claude Code carga archivos .js y .ts directamente.

​

Pida a Claude un mod

​

Use el mod en otras sesiones

• En una sesión que inicia: en su shell, ejecute claude --plugin-dir ~/mods/git-branch
• Para otras personas: agréguelo a un marketplace para que puedan instalarlo

​

Sesiones donde un mod que Claude escribe no puede cargarse

• Nadie está allí para aprobar: la sesión no puede mostrarle un símbolo del sistema, como en una ejecución claude -p o modo dontAsk
• El espacio de trabajo no es de confianza: no ha aceptado el símbolo del sistema de confianza para el directorio
• Los mods están detenidos: comenzó con --safe-mode o --bare, estableció disableAllHooks, o la configuración administrada de su organización lo bloquea

​

Escriba un mod usted mismo

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

• plugin.json: el manifiesto del plugin
• hooks.json: apunta a su archivo de código
• register.js: su código, llamado el módulo de 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 + '…' } })
  })

​

Cómo funciona el mod de ejemplo

• La API de mods, llamada $: cada método que un mod puede llamar para llegar fuera de sí mismo, en espacios de nombres como $.ui y $.command
• El evento, llamado e: la entrada del evento como datos simples, como el nombre y los argumentos de una llamada de herramienta
• El siguiente controlador, llamado next: una función que pasa el evento a los otros mods y luego al comportamiento propio de Claude Code, y devuelve el resultado

• Observar: el hook session.start registra el comando, y el hook tool.call cuenta la llamada y pide un redibujado. Ambos devuelven next(e), por lo que la sesión comienza y la herramienta se ejecuta como de costumbre.
• Responder: el hook command.run devuelve su propio resultado y nunca llama a next. El segundo argumento a on, { command: 'tally' }, es un filtro, llamado un matcher, por lo que el hook se ejecuta solo para /tally.
• Reescribir: el hook ui.render llama a next con una copia de e cuyo suffix contiene el recuento, por lo que Claude Code dibuja su spinner habitual con su texto después de la palabra

​

Continúe trabajando en un mod

​

Cambie un mod con Claude

claude --plugin-dir ./first-mod

​

Obtenga definiciones de tipo para su versión

​

Verifique qué Claude Code lee de su 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

• Deletree cada llamada de la API de mods en su totalidad: $, el espacio de nombres, luego el método, como en $.store.get('notes'). Puede pasar $ a una función declarada en el nivel superior del mismo archivo, y para una función suya llamada loadNotes, la línea calls: entonces lee $.store.get (via loadNotes). Pasar $ a un método, una función definida dentro del hook, o una función que importa de otro de sus archivos falla la validación. Las funciones read y update que $.state usa son las importaciones que pueden tomarlo. No asigne $ o uno de sus espacios de nombres a una variable, desestructúrelo, o indexarlo con un nombre calculado. const ui = $.ui falla con $.ui is used as a value.
• Escriba el nombre del evento en cada llamada a on como un literal de cadena, como 'tool.call'. Una variable, o un bucle sobre una lista de nombres, falla con the event name passed to on() is not a string literal.
• Dentro de register, no declare una segunda variable o parámetro llamado on. La validación falla con "on" is declared again (shadowed).
• Importe solo desde archivos dentro del directorio del plugin, por ruta relativa. La única importación desnuda permitida es claude-code, para tipos y algunos ayudantes.
• Use declaraciones import en la parte superior del archivo, como en import { name } from './file.js'. Un import() dinámico falla con a dynamic import(); a hooks module imports its own files with an import declaration.
• Escriba cada archivo como un módulo ES, con import y no require. La referencia enumera las extensiones de archivo que Claude Code carga.

​

Pruebe el 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]

​

Comparta su mod

​

Próximos pasos

• Dibuje en la interfaz: abra un panel, dibuje encima del símbolo del sistema, y agregue botones y campos de texto
• Reaccione a eventos: enganche llamadas de herramientas, símboles del sistema, y turnos
• Use la API de mods: agregue comandos y herramientas, llame a un modelo, y ejecute trabajo en un temporizador
• Pruebe un mod: stub lo que Claude Code respondería, y pruebe temporizadores y dibujos
• Solucione problemas de un mod: las razones por las que un mod no hace nada, y el registro de depuración
• Lea la fuente de mods integrados: plugins completos, cada uno con su módulo de hooks y pruebas