Erstelle einen Mod

• Claude bitten, ihn zu schreiben: beschreibe, was du möchtest in einer Claude Code Sitzung
• Schreibe ihn selbst: folge dem Tutorial, um zu lernen, wie der Code eines Mods funktioniert. Du brauchst Node.js, einen Bundler oder einen Build-Schritt nicht, da Claude Code .js und .ts Dateien direkt lädt.

​

Claude um einen Mod bitten

​

Verwende den Mod in anderen Sitzungen

• In einer Sitzung, die du startest: Führe in deiner Shell claude --plugin-dir ~/mods/git-branch aus
• Für andere Personen: Füge ihn zu einem Marketplace hinzu, damit sie ihn installieren können

​

Sitzungen, in denen ein von Claude geschriebener Mod nicht geladen werden kann

• Niemand ist da, um zu genehmigen: Die Sitzung kann dir keine Eingabeaufforderung anzeigen, wie in einem claude -p Lauf oder im dontAsk Modus
• Der Arbeitsbereich ist nicht vertrauenswürdig: Du hast die Vertrauensaufforderung für das Verzeichnis nicht akzeptiert
• Mods sind gestoppt: Du hast mit --safe-mode oder --bare gestartet, du hast disableAllHooks gesetzt, oder die verwalteten Einstellungen deiner Organisation blockieren es

​

Schreibe einen Mod selbst

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

• plugin.json: das Manifest des Plugins
• hooks.json: verweist auf deine Codedatei
• register.js: dein Code, genannt das 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

• Die Mods API, genannt $: jede Methode, die ein Mod aufrufen kann, um sich selbst zu erreichen, in Namespaces wie $.ui und $.command
• Das Ereignis, genannt e: die Eingabe des Ereignisses als einfache Daten, wie der Name und die Argumente eines Werkzeugaufrufs
• Der nächste Handler, genannt next: eine Funktion, die das Ereignis an die anderen Mods und dann an Claude Codes eigenes Verhalten weiterleitet und das Ergebnis zurückgibt

• Beobachten: Der session.start Hook registriert den Befehl, und der tool.call Hook zählt den Aufruf und bittet um eine Neuzeichnung. Beide geben next(e) zurück, sodass die Sitzung startet und das Werkzeug wie gewohnt läuft.
• Antworten: Der command.run Hook gibt sein eigenes Ergebnis zurück und ruft niemals next auf. Das zweite Argument zu on, { command: 'tally' }, ist ein Filter, genannt ein Matcher, sodass der Hook nur für /tally läuft.
• Umschreiben: Der ui.render Hook ruft next mit einer Kopie von e auf, deren suffix die Anzahl hält, sodass Claude Code seinen üblichen Spinner mit deinem Text nach dem Wort zeichnet

​

Arbeite weiter an einem Mod

​

Ändere einen Mod mit Claude

claude --plugin-dir ./first-mod

​

Erhalte Typdeklarationen für deine Version

​

Überprüfe, was Claude Code aus deinem Mod liest

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

• Schreibe jeden Mods API Aufruf vollständig: $, den Namespace, dann die Methode, wie in $.store.get('notes'). Du kannst $ an eine Funktion übergeben, die auf der obersten Ebene der gleichen Datei deklariert ist, und für eine Funktion von dir namens loadNotes, liest die calls: Zeile dann $.store.get (via loadNotes). Das Übergeben von $ an eine Methode, eine Funktion, die im Hook definiert ist, oder eine Funktion, die du aus einer anderen deiner Dateien importierst, schlägt die Validierung fehl. Die read und update Funktionen, die $.state verwendet, sind die Importe, die es nehmen können. Weise $ oder einen seiner Namespaces nicht einer Variablen zu, destrukturiere ihn nicht, und indexiere ihn nicht mit einem berechneten Namen. const ui = $.ui schlägt mit $.ui is used as a value fehl.
• Schreibe den Ereignisnamen in jedem on Aufruf als String-Literal, wie '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.
• Deklariere innerhalb von register keine zweite Variable oder keinen Parameter namens on. Die Validierung schlägt mit "on" is declared again (shadowed) fehl.
• Importiere nur aus Dateien im Plugin-Verzeichnis, nach relativem Pfad. Der einzige erlaubte bloße Import ist claude-code, für Typen und ein paar Helfer.
• Verwende import Deklarationen am Anfang der Datei, wie in import { name } from './file.js'. Ein dynamischer import() schlägt mit a dynamic import(); a hooks module imports its own files with an import declaration fehl.
• Schreibe jede Datei als ES-Modul, mit import und nicht require. Die Referenz listet die Dateierweiterungen auf, die Claude Code lädt.

​

Teste den 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]

​

Teile deinen Mod

​

Nächste Schritte

• Zeichne in der Schnittstelle: öffne einen Bereich, zeichne über der Eingabeaufforderung, und füge Schaltflächen und Textfelder hinzu
• Reagiere auf Ereignisse: hook Werkzeugaufrufe, Eingabeaufforderungen und Runden
• Verwende die Mods API: füge Befehle und Werkzeuge hinzu, rufe ein Modell auf, und führe Arbeit auf einem Timer aus
• Teste einen Mod: stub, was Claude Code antworten würde, und teste Timer und Zeichnungen
• Behebe einen Mod: die Gründe, warum ein Mod nichts tut, und das Debug-Protokoll
• Lese die Quelle von integrierten Mods: vollständige Plugins, jeweils mit seinem Hooks-Modul und Tests