Créer un mod

• Demander à Claude de l’écrire : décrivez ce que vous voulez dans une session Claude Code
• L’écrire vous-même : suivez le tutoriel pour apprendre comment fonctionne le code d’un mod. Vous n’avez pas besoin de Node.js, d’un bundler ou d’une étape de build, car Claude Code charge les fichiers .js et .ts directement.

​

Demander à Claude un mod

​

Utilisez le mod dans d’autres sessions

• Dans une session que vous démarrez : dans votre shell, exécutez claude --plugin-dir ~/mods/git-branch
• Pour d’autres personnes : ajoutez-le à une marketplace pour qu’elles puissent l’installer

​

Sessions où un mod que Claude écrit ne peut pas se charger

• Personne n’est là pour approuver : la session ne peut pas vous montrer une invite, comme dans une exécution claude -p ou en mode dontAsk
• L’espace de travail n’est pas de confiance : vous n’avez pas accepté l’invite de confiance pour le répertoire
• Les mods sont arrêtés : vous avez démarré avec --safe-mode ou --bare, vous avez défini disableAllHooks, ou les paramètres gérés de votre organisation le bloquent

​

Écrivez un mod vous-même

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

• plugin.json : le manifeste du plugin
• hooks.json : pointe vers votre fichier de code
• register.js : votre code, appelé le module 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 + '…' } })
  })

​

Comment fonctionne le mod d’exemple

• L’API des mods, nommée $ : chaque méthode qu’un mod peut appeler pour atteindre l’extérieur de lui-même, dans des espaces de noms tels que $.ui et $.command
• L’événement, nommé e : l’entrée de l’événement en tant que données simples, comme le nom et les arguments d’un appel d’outil
• Le gestionnaire suivant, nommé next : une fonction qui transmet l’événement aux autres mods puis au comportement propre de Claude Code, et retourne le résultat

• Observer : le hook session.start enregistre la commande, et le hook tool.call compte l’appel et demande un redessinage. Les deux retournent next(e), donc la session démarre et l’outil s’exécute comme d’habitude.
• Répondre : le hook command.run retourne son propre résultat et n’appelle jamais next. Le deuxième argument à on, { command: 'tally' }, est un filtre, appelé un matcher, donc le hook s’exécute uniquement pour /tally.
• Réécrire : le hook ui.render appelle next avec une copie de e dont suffix contient le compte, donc Claude Code dessine son spinner habituel avec votre texte après le mot

​

Continuez à travailler sur un mod

​

Modifiez un mod avec Claude

claude --plugin-dir ./first-mod

​

Obtenez les définitions de type pour votre version

​

Vérifiez ce que Claude Code lit à partir de votre 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

• Épellez chaque appel de l’API des mods en entier : $, l’espace de noms, puis la méthode, comme dans $.store.get('notes'). Vous pouvez passer $ à une fonction déclarée au niveau supérieur du même fichier, et pour une fonction vôtre nommée loadNotes, la ligne calls: lit alors $.store.get (via loadNotes). Passer $ à une méthode, une fonction définie à l’intérieur du hook, ou une fonction que vous importez d’un autre de vos fichiers échoue la validation. Les fonctions read et update que $.state utilise sont les imports qui peuvent le prendre. N’assignez pas $ ou l’un de ses espaces de noms à une variable, ne le déstructurez pas, ou ne l’indexez pas avec un nom calculé. const ui = $.ui échoue avec $.ui is used as a value.
• Écrivez le nom de l’événement dans chaque appel on comme un littéral de chaîne, comme 'tool.call'. Une variable, ou une boucle sur une liste de noms, échoue avec the event name passed to on() is not a string literal.
• À l’intérieur de register, ne déclarez pas une deuxième variable ou paramètre nommé on. La validation échoue avec "on" is declared again (shadowed).
• Importez uniquement à partir de fichiers à l’intérieur du répertoire du plugin, par chemin relatif. Le seul import nu autorisé est claude-code, pour les types et quelques helpers.
• Utilisez les déclarations import en haut du fichier, comme dans import { name } from './file.js'. Un import() dynamique échoue avec a dynamic import(); a hooks module imports its own files with an import declaration.
• Écrivez chaque fichier en tant que module ES, avec import et non require. La référence liste les extensions de fichier que Claude Code charge.

​

Testez le 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]

​

Partagez votre mod

​

Prochaines étapes

• Dessinez dans l’interface : ouvrez un volet, dessinez au-dessus de l’invite, et ajoutez des boutons et des champs de texte
• Réagissez aux événements : hooquez les appels d’outils, les invites, et les tours
• Utilisez l’API des mods : ajoutez des commandes et des outils, appelez un modèle, et exécutez du travail sur un minuteur
• Testez un mod : stubifiez ce que Claude Code répondrait, et testez les minuteurs et les dessins
• Dépannez un mod : les raisons pour lesquelles un mod ne fait rien, et le journal de débogage
• Lisez la source des mods intégrés : des plugins complets, chacun avec son module de hooks et ses tests