Sie schreiben drei Dateien:

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

• plugin.json: das Manifest des Plugins
• hooks.json: verweist auf Ihre Codedatei
• register.js: Ihr Code, das sogenannte Hooks-Modul

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

Wie der Beispiel-Mod funktioniert

Jede Funktion, die Sie an on übergeben, ist ein Hook, also ein Event-Handler. Claude Code übergibt jedem Hook dieselben drei Argumente:

• Die Mods-API, namens $: alle Methoden, die ein Mod aufrufen kann, um über sich selbst hinaus zu wirken, in Namespaces wie $.ui und $.command
• Das Event, namens e: die Eingabe des Events als einfache Daten, etwa Name und Argumente eines Tool-Aufrufs
• Der nächste Handler, namens next: eine Funktion, die das Event an die anderen Mods und dann an das eigene Verhalten von Claude Code weitergibt und das Ergebnis zurückgibt

Die Hooks in first-mod behandeln ihre Events auf folgende Weise:

• Beobachten: Der Hook session.start registriert den Befehl, und der Hook tool.call zählt den Aufruf und fordert ein Neuzeichnen an. Beide geben next(e) zurück, sodass die Sitzung startet und das Tool wie gewohnt ausgeführt wird.
• Antworten: Der Hook command.run gibt sein eigenes Ergebnis zurück und ruft next nie auf. Das zweite Argument von on, { command: 'tally' }, ist ein Filter, ein sogenannter Matcher, sodass der Hook nur für /tally ausgeführt wird.
• Umschreiben: Der Hook ui.render ruft next mit einer Kopie von e auf, deren suffix die Anzahl enthält, sodass Claude Code seinen gewohnten Spinner mit Ihrem Text nach dem Wort zeichnet

Claude Code überwacht ein mit --plugin-dir geladenes Verzeichnis und lädt das Hooks-Modul per Hot-Reload neu, wenn sich eine Datei darin ändert. Bei jedem Neuladen wird register erneut ausgeführt, sodass calls auf 0 zurückgesetzt wird und /tally von vorn zu zählen beginnt. Wie Sie einen Wert über Neuladevorgänge hinweg behalten, erfahren Sie unter Zustand beibehalten.

An einem Mod weiterarbeiten

Sobald ein Mod geladen ist, können Sie Claude Änderungen daran vornehmen lassen, Ihren Code mit den Typdefinitionen für Ihre Version abgleichen, die Events und Aufrufe auflisten, die Claude Code darin findet, und den Mod testen.

Einen Mod mit Claude ändern

Um einen vorhandenen Mod zu ändern, starten Sie die Sitzung mit --plugin-dir, das auf das Verzeichnis des Mods zeigt, damit das, was Claude schreibt, in derselben Sitzung geladen wird:

claude --plugin-dir ./first-mod

Bitten Sie dann um die Änderung, zum Beispiel add a /tally-reset command to this mod that sets the tally back to zero. Claude bearbeitet das Hooks-Modul, führt claude plugin validate aus und behebt, was gemeldet wird. Ein Verzeichnis, das Sie mit --plugin-dir laden, ist ein geschützter Pfad, daher werden Sie in den Modi default und acceptEdits gebeten, jede Bearbeitung des Mods durch Claude zu genehmigen. Die Tabelle der geschützten Pfade zeigt das Ergebnis für die anderen Berechtigungsmodi.

Dateien, die Claude während seines Turns speichert, werden am Ende des Turns neu geladen, sodass Sie /tally-reset ausprobieren können, sobald Claude fertig ist.

Typdefinitionen für Ihre Version erhalten

Jedes Mal, wenn Claude Code einen Mod aus einem Verzeichnis lädt oder neu lädt, das Sie an --plugin-dir übergeben, oder einen Mod, den Claude für Sie geschrieben hat, schreibt es TypeScript-Deklarationsdateien mit der Endung .d.ts in .claude-plugin/types/ innerhalb des Mod-Verzeichnisses. Sie beschreiben die genauen Events, Methoden der Mods-API und Elemente in der Claude Code-Version, die Sie ausführen, sodass Ihr Editor Ihre Hooks automatisch vervollständigen und typprüfen kann. Um die Deklarationen online einzusehen, lesen Sie mods/types/claude-code.d.ts im Claude Code-Repository; die erste Zeile nennt die Version, die die Datei geschrieben hat. Das Verzeichnis enthält diese Dateien:

Wenn Ihr Mod keine eigene tsconfig.json hat, fügt Claude Code im Stammverzeichnis des Mods eine hinzu, die die generierte erweitert, sodass Ihr Editor und tsc -p ./first-mod den Mod ohne weitere Einrichtung typprüfen.

Die Events und Methoden können sich zwischen Releases ändern. Vertrauen Sie daher im Zweifelsfall diesen Dateien mehr als jeder Seite, einschließlich dieser.

claude-code/index.d.ts ist die umfassendste Referenz für Ihren Build, mit einem Kommentar und einem Beispiel für jede Methode der Mods-API. Um etwas nachzuschlagen, durchsuchen Sie die Datei nach dem Namen, etwa 'tool.call'.

Prüfen, was Claude Code aus Ihrem Mod liest

Um Ihren Mod so zu sehen, wie Claude Code ihn sieht, ohne Ihren Code auszuführen oder eine Sitzung zu starten, verwenden Sie claude plugin validate. Der Befehl prüft das Manifest und führt auf dem Quellcode des Hooks-Moduls dieselbe statische Analyse aus, die Claude Code beim Laden eines Mods ausführt. Führen Sie ihn in Ihrer Shell auf dem Verzeichnis des Mods aus:

claude plugin validate ./first-mod

Für first-mod enthält die Ausgabe diese Zeilen.

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

✔ Validation passed

Die Zeile hooks: listet die Events auf, an die sich Ihr Modul hängt, jeweils mit seinem Filter in geschweiften Klammern. Die Zeile calls: listet jede Methode der Mods-API auf, die es aufruft. Ein Modul, das Umgebungsvariablen liest oder setzt, erhält außerdem die Zeilen env reads: und env writes:, und eines, das $.state verwendet, erhält state reads: und state writes:.

Wenn ein Event, das Sie behandeln wollten, in der ersten Zeile fehlt, ruft Claude Code diesen Hook ebenfalls nicht auf. Die übliche Ursache ist ein falsch geschriebener Event-Name, den der Befehl als Fehler meldet, etwa "tool.calls" is not an event.

Befolgen Sie diese Regeln, damit die statische Analyse jeden Hook und jeden Aufruf finden kann:

• Schreiben Sie jeden Aufruf der Mods-API vollständig aus: $, den Namespace, dann die Methode, wie in $.store.get('notes'). Sie können $ an eine Funktion übergeben, die auf oberster Ebene derselben Datei deklariert ist; für eine eigene Funktion namens loadNotes lautet die Zeile calls: dann $.store.get (via loadNotes). Wenn Sie $ an eine Methode, an eine innerhalb des Hooks definierte Funktion oder an eine aus einer anderen Ihrer Dateien importierte Funktion übergeben, schlägt die Validierung fehl. Die Funktionen read und update, die $.state verwendet, sind die Importe, die es entgegennehmen können. Weisen Sie $ oder einen seiner Namespaces keiner Variablen zu, destrukturieren Sie es nicht und indizieren Sie es nicht mit einem berechneten Namen. const ui = $.ui schlägt mit $.ui is used as a value fehl.
• Schreiben Sie den Event-Namen in jedem on-Aufruf als String-Literal, etwa 'tool.call'. Eine Variable oder eine Schleife über eine Liste von Namen schlägt mit the event name passed to on() is not a string literal fehl.
• Deklarieren Sie innerhalb von register keine zweite Variable und keinen zweiten Parameter namens on. Die Validierung schlägt mit "on" is declared again (shadowed) fehl.
• Importieren Sie nur aus Dateien innerhalb des Plugin-Verzeichnisses, über einen relativen Pfad. Der einzige erlaubte Bare Import ist claude-code, für Typen und einige Hilfsfunktionen.
• Verwenden Sie import-Deklarationen am Anfang der Datei, wie in import { name } from './file.js'. Ein dynamisches import() schlägt mit a dynamic import(); a hooks module imports its own files with an import declaration fehl.
• Schreiben Sie jede Datei als ES-Modul, mit import und nicht mit require. Die Referenz listet die Dateiendungen auf, die Claude Code lädt.

Den Mod testen

Sie können automatisierte Tests für einen Mod schreiben und sie in Ihrer Shell mit claude plugin test ausführen, ohne Sitzung, Anmeldung oder Netzwerk. Ein Test löst die Events aus, die Ihre Hooks behandeln, und prüft, was die Hooks getan haben.

Dieser Test löst zwei Tool-Aufrufe aus, führt /tally aus und prüft, dass die Antwort beide zählt. Speichern Sie ihn als 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')
})

Führen Sie die Tests in Ihrer Shell im Verzeichnis first-mod aus:

claude plugin test

Die Ausgabe nennt jeden Test und ob er bestanden wurde, mit Zeitangaben, die von Lauf zu Lauf variieren:

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]

Einen Mod testen behandelt das Stubben eines Modellaufrufs oder des Stores sowie das Testen von Timern und Zeichnungen.

Ihren Mod teilen

Ein Mod ist ein Plugin. Sie versionieren ihn also im Manifest, und andere installieren und aktualisieren ihn mit den /plugin-Befehlen. Wie Sie ihn teilen, hängt davon ab, für wen er gedacht ist:

• Einige wenige Personen: Senden Sie ihnen das Verzeichnis des Plugins oder eine .zip-Datei davon. Siehe Ein Plugin ohne Marketplace teilen
• Ihr Team: Führen Sie ihn in Ihrem eigenen Marketplace auf, etwa in einem privaten Repository mit einem Verzeichnis für jedes Plugin. Um diesen Marketplace für alle hinzuzufügen, die in einem Repository arbeiten, registrieren Sie ihn in den Einstellungen des Repositorys
• Ihre gesamte Organisation: Ein Administrator kann die Mods Ihrer Organisation über verwaltete Einstellungen installieren
• Alle: Machen Sie das Repository Ihres Marketplace öffentlich, oder reichen Sie das Plugin beim Verzeichnis von Anthropic ein

Prüfen Sie vorher den name des Plugins: claude plugin validate lehnt einen Namen ab, der wie einer von Anthropics eigenen aussieht, etwa einen, der mit claude- beginnt. Die Events und Methoden können sich zwischen Releases ändern. Geben Sie daher in Ihrer README an, mit welcher Claude Code-Version Sie getestet haben.

Entwickeln Sie weiterhin mit --plugin-dir gegen das Verzeichnis, nicht gegen eine installierte Kopie. Claude Code speichert ein installiertes Plugin versionsweise im Cache. Ihre Änderungen erreichen die installierte Kopie daher erst, wenn Sie die Version erhöhen und erneut installieren.

Nächste Schritte

• In der Oberfläche zeichnen: einen Bereich öffnen, oberhalb des Prompts zeichnen und Schaltflächen sowie Textfelder hinzufügen
• Auf Ereignisse reagieren: Tool-Aufrufe, Prompts und Turns abfangen
• Die Mods-API verwenden: Befehle und Tools hinzufügen, ein Modell aufrufen und Aufgaben per Timer ausführen
• Einen Mod testen: die Antworten von Claude Code simulieren sowie Timer und Zeichnungen testen
• Fehlerbehebung bei einem Mod: die Gründe, warum ein Mod nichts tut, und das Debug-Log
• Den Quellcode der integrierten Mods lesen: vollständige Plugins, jeweils mit ihrem Hooks-Modul und Tests