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 Code-Datei
• register.js: Ihr Code, Hooks-Modul genannt

1. Plugin-Verzeichnis erstellen

Erstellen Sie die beiden Verzeichnisse, die die Dateien enthalten:

[tab] Bash oder Zsh

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

[tab] PowerShell

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

2. Manifest schreiben

Ein Mod ist ein Plugin, und ein Mod benötigt ein Manifest. Das Manifest dieses Mods hat keine besonderen Felder. Speichern Sie Folgendes als first-mod/.claude-plugin/plugin.json:

{
  "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" }
}

3. Claude Code mitteilen, wo Ihr Code liegt

Wenn Claude Code ein Plugin lädt, liest es die Datei hooks/hooks.json des Plugins. Der Schlüssel modules in dieser Datei gibt den Pfad zu Ihrem Code an, und genau dieser Schlüssel macht das Plugin zu einem Mod. Geben Sie einen Pfad relativ zu hooks.json an. Hier verweist er auf register.js, die Sie im nächsten Schritt schreiben.

Speichern Sie Folgendes als first-mod/hooks/hooks.json:

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

4. Code schreiben

Diese Datei ist der Code des Mods, Hooks-Modul genannt. Wenn der Mod geladen wird, ruft Claude Code die Funktion register auf, die die Datei exportiert, und übergibt ihr eine Funktion namens on. Jeder Aufruf von on registriert einen Event-Handler, Hook genannt, für das Event, das er benennt.

Speichern Sie Folgendes als first-mod/hooks/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 + '…' } })
  })
}

Die Datei speichert eine Anzahl in calls und registriert vier Hooks:

• session.start wird ausgeführt, wenn die Sitzung startet, vor Ihrem ersten Prompt, und erneut bei jedem Neuladen des Mods. Er fügt Claude Code den Befehl /tally hinzu.
• tool.call wird jedes Mal ausgeführt, wenn Claude im Begriff ist, ein Tool zu verwenden. Er erhöht calls um eins und fordert Claude Code auf, die Oberfläche neu zu zeichnen.
• command.run wird ausgeführt, wenn Sie /tally eingeben. Er gibt den auszugebenden Text zurück.
• ui.render wird jedes Mal ausgeführt, wenn Claude Code den Spinner zeichnet. Er fügt die Anzahl nach dem Wort des Spinners hinzu.

Wie der Beispiel-Mod funktioniert erklärt die drei Argumente, die jeder Hook erhält, und was jeder zurückgibt.

5. Mod laden

Starten Sie Claude Code mit dem Flag --plugin-dir, das ein Plugin-Verzeichnis für eine Sitzung lädt, ohne es zu installieren:

claude --plugin-dir ./first-mod

6. Mod ausprobieren

Bitten Sie Claude um etwas, das einige Tool-Aufrufe erfordert, zum Beispiel list the files here and read the README. Während Claude arbeitet, folgt auf das Wort des Spinners eine steigende Anzahl, wie in Thinking · tool calls: 2…. Wenn Claude fertig ist, geben Sie /tally ein und drücken Sie Enter. Das Transkript zeigt first-mod: Claude has made 2 tool calls since this mod loaded mit Ihrer eigenen Anzahl. Claude Code stellt den Namen des Plugins vor den Text des Befehls.

Um den Befehl ohne interaktive Sitzung zu prüfen, führen Sie ihn im nicht interaktiven Modus aus:

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

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

Wenn /tally nicht in der Befehlsliste erscheint, wurde das Modul nicht geladen. Siehe Herausfinden, warum ein Mod nichts tut.

7. Code ändern, während die Sitzung läuft

Lassen Sie die Sitzung geöffnet. Ändern Sie in register.js im Hook ui.render ' · tool calls: ' zu ' · tools used: ' und speichern Sie. Die hervorgehobene Zeile ist die, die sich ändert:

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

Eine Zeile im Transkript meldet, dass first-mod neu geladen wurde, und listet seine Hooks auf, und der nächste Spinner verwendet den neuen Text, wie in Thinking · tools used: 1….

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, $ genannt: jede Methode, die ein Mod aufrufen kann, um über sich selbst hinauszugreifen, in Namespaces wie $.ui und $.command
• Das Event, e genannt: die Eingabe des Events als einfache Daten, etwa Name und Argumente eines Tool-Aufrufs
• Der nächste Handler, next genannt: 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.
• Beantworten: 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, Matcher genannt, 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 im laufenden Betrieb neu, wenn sich eine Datei darin ändert. Jedes Neuladen führt register erneut aus, sodass calls auf 0 zurückgesetzt wird und /tally von vorn zu zählen beginnt. Um einen Wert über Neuladevorgänge hinweg zu behalten, siehe 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

Wenn Claude Code in einer interaktiven Sitzung einen Mod aus --plugin-dir lädt oder einen Mod, den Claude für Sie geschrieben hat, schreibt es TypeScript-Deklarationsdateien in das Verzeichnis .claude-plugin/types/ des Mods. 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. 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

Prüfen Sie in der Zeile hooks: die Events, an die sich Ihr Modul hängt, jeweils mit seinem Filter in geschweiften Klammern, und in der Zeile calls: jede Methode der Mods-API, die es aufruft. Wenn Ihr Modul Umgebungsvariablen liest oder setzt, achten Sie außerdem auf die Zeilen env reads: und env writes:, und auf state reads: und state writes:, wenn es $.state verwendet. Außerdem sehen Sie für jeden Hook, der eine Aktion ablehnen kann, eine Zeile wie gating hook without .catch: tool.call, die angibt, ob dieser Hook einen .catch-Handler hat.

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