Zum Hauptinhalt springen
Schlagen Sie jedes Event nach, das ein Mod verarbeiten kann, jede Methode der Mods-API, die er aufrufen kann, und jede Render-Stelle, an der er zeichnen kann. Die Einträge gelten für die Claude Code CLI und die Desktop-App ab v2.1.290 sowie für die VS Code-Erweiterung ab v2.1.299. Jeder Eintrag enthält den Namen und eine einzeilige Beschreibung sowie, sofern vorhanden, einen Link zum Abschnitt des Leitfadens, der ihn erklärt.
Die vollständige Referenz sind die TypeScript-Deklarationen für Mods von Claude Code, die jedes Event, jede Methode und jedes Element mit Beispielen beschreiben. Die Kopie auf GitHub kann älter sein als die installierte Version von Claude Code. Wenn die beiden voneinander abweichen, verlassen Sie sich auf die Kopie, die Claude Code für Ihre Version schreibt.

​
Dateien

Ein Mod ist ein Plugin-Verzeichnis mit diesen Dateien: register erhält on und options. options enthält die Werte der userConfig-Felder, die das Manifest deklariert, wobei Standardwerte ergänzt werden.

​
Die Hook-Funktion

Ein Mod registriert jeden seiner Hooks, also Event-Handler, indem er on innerhalb von register aufruft. on nimmt den Namen des Events, einen optionalen Matcher, also einen Filter auf die Felder des Events, und den Hook entgegen, wie in on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on gibt eine Registrierung mit einer Methode zurück, .catch(handler), die den Fehler-Handler des Hooks festlegt.

​
Events

Events sind danach gruppiert, was sie betreffen, jeweils mit der Angabe, wann sie ausgelöst werden und was ein Hook darauf zurückgeben kann. Hooks auf turn.step und process.spawn sind asynchrone Generatoren, andere Hooks sind asynchrone Funktionen. Die letzte Spalte jeder Tabelle verwendet eine Kurzschreibweise. next(e) gibt das Event unverändert weiter. next({ ...e, text }) gibt eine Kopie mit dem genannten geänderten Feld weiter, wie in next({ ...e, text: e.text.trim() }). Ein Objekt beantwortet das Event, ohne next aufzurufen, und ein Wort wie reason steht für einen String, den Sie schreiben, wie in { deny: 'Use the file tools.' }.

​
Tools

Tool-Events werden rund um jeden Tool-Aufruf ausgelöst, den Claude durchführt, von der Beschreibung, die Claude liest, bis zur Entscheidung, ob der Aufruf ausgeführt wird:

​
Agenten- und Organisationsfelder in tool.check

Lesen Sie in einem tool.check-Hook diese Felder, um den Aufruf eines Subagenten von dem der Hauptkonversation zu unterscheiden und um zu sehen, ob Ihre Organisation für ein Konnektor-Tool eine Genehmigung verlangt: Bei tool.check erfordern e.agentId und e.ceiling Claude Code v2.1.290 oder höher.

​
Das Feld e.isReadOnly in tool.check

In einem tool.check-Hook ist e.isReadOnly gleich true, wenn das Tool diesen Aufruf als nur lesend meldet. Andernfalls ist das Feld nicht vorhanden, statt false zu sein. Der Wert ist die eigene Angabe des Tools. Lesen Sie daher Prüfen, ob ein Tool-Aufruf nur lesend ist, bevor Sie einen Aufruf allein anhand dieses Felds genehmigen. Bei tool.check erfordert e.isReadOnly Claude Code v2.1.304 oder höher.

​
Prompts und was Claude liest

Prompt-Events betreffen den Text, den der Benutzer eingibt, und den Text, den Claude Code von sich aus an Claude sendet, etwa den System-Prompt und Erinnerungen:

​
Quell- und Frontmatter-Felder in skill.prompt

In einem skill.prompt-Hook können Sie diese Felder zusammen mit dem Namen des Skills in e.skill und dem Text, den Claude liest, in e.text lesen: Ein Hook kann einen geänderten text oder ein geändertes frontmatter an next übergeben: Die Hooks danach lesen beides, und Claude liest den endgültigen text. Ein Hook, der ein anderes Feld ändert, schlägt fehl. Bei skill.prompt erfordern e.source, e.pluginName, e.path, e.frontmatter und e.frontmatterProblem Claude Code v2.1.299 oder höher.

​
Befehle und Konfiguration

​
e.layers und e.source in settings.read

  • e.layers: ein { source, settings }-Objekt für jede verwendete Quelle, die Einstellungen enthält, mit dem niedrigsten Vorrang zuerst. Siehe Was ein settings.read-Hook erhält.
  • e.source: die eine Quelle, die ein Mod angefordert hat, wie in $.settings.read({ source: 'policy' }). Nicht vorhanden beim eigenen Lesevorgang von Claude Code und bei einem Lesevorgang der zusammengeführten Einstellungen

​
Turns

Turn-Events verfolgen eine Antwort von Anfang bis Ende, einschließlich jeder Anfrage an das Modell darin:

​
Sitzung

Sitzungs-Events markieren, dass die Sitzung startet, endet, komprimiert wird und Nachrichten mit anderen Sitzungen austauscht:

​
Subagenten

Subagenten-Events werden ausgelöst, wenn Claude ein Subagenten-Typ angeboten wird und wenn ein Subagent oder ein Teammitglied eines Agent-Teams gleich startet: Wenn Claude einen Subagenten mit dem Tool SendMessage fortsetzt, wird Ihr agent.spawn-Hook nicht erneut ausgeführt. Um die SendMessage-Aufrufe abzulehnen, die einen Subagenten fortsetzen, gleichen Sie dieses Tool in einem tool.call-Hook ab.

​
Oberfläche

Oberflächen-Events werden ausgelöst, wenn Claude Code eine Render-Stelle zeichnet und wenn der Benutzer ein Steuerelement verwendet, das ein Mod gezeichnet hat. In der Oberfläche zeichnen zeigt, was ein ui.render-Hook zurückgibt:

​
Andere Mods

Mit diesen Events kann ein Mod auf andere Mods einwirken, während sie geladen werden, um einen abzulehnen oder die Mods-API zu ändern, die er erhält: Wenn der Hook eines anderen Mods eine Methode in einem Namespace aufruft, den Sie in engine.create hinzugefügt haben, laufen die $-Aufrufe Ihrer Methode im Kontext dieses Hooks, bis jeder Hook auf diesem Event zurückgekehrt ist. Beispielsweise wird ein relativer Pfad relativ zum Arbeitsverzeichnis dieses Hooks aufgelöst, und $.prompt.submit wird abgelehnt, solange der Turn auf diesen Hook wartet. Aufrufe, die Ihre Methode danach durchführt, laufen im eigenen Kontext Ihres Mods.

​
Telemetrie

Telemetrie-Events werden für die Nutzungsdatensätze ausgelöst, die Claude Code protokolliert:

​
Events von Einstellungs-Hooks

Jedes Event eines Einstellungs-Hooks ist ein Event mit dem Namen classic.<Event>, etwa classic.Stop oder classic.PostToolUse. e ist das stdin-JSON des Hooks.

​
Mods-API-Aufrufe

Jede Mods-API-Methode ist auch ein Event, benannt nach ihrem Namespace und ihrer Methode, etwa fs.read, model.complete oder ui.open. Ein Hook darauf fängt Aufrufe der Mods ab, die nach ihm ausgeführt werden, und kann next(e), { deny: reason } oder { value } zurückgeben.

​
Methoden der Mods-API

Die Mods-API ist das Argument $, das jeder Hook erhält. Ihre Methoden sind in Namespaces gruppiert, etwa $.ui. Diese Tabelle listet die Methoden jedes Namespace nach Namen auf, sodass open in der Zeile $.ui dem Aufruf $.ui.open(...) entspricht. Die Leitfäden zeigen die gängigen Methoden im Einsatz, und die Typen für Ihren Build dokumentieren jede Methode mit einem Beispiel.

​
Render-Stellen

Eine Render-Stelle ist ein Erweiterungspunkt in der Oberfläche von Claude Code. Jede Zeile ist ein Wert von e.component in einem ui.render-Hook, mit den Feldern von e.props und den Apps, die sie rendern. e.surface benennt die App, die zeichnet, etwa terminal, desktop oder vscode. Ändern, was Claude Code bereits zeichnet zeigt, was ein Hook an einer Stelle tun kann, mit einem Beispiel für jede Möglichkeit. Das Rendern in der VS Code-Erweiterung erfordert die Erweiterungsversion 2.1.299 oder höher. Eine Sitzung, die keine Feature-Flags abruft, benötigt 2.1.304 oder höher. In der VS Code-Erweiterung zeichnen listet auf, was die Erweiterung anders zeichnet. e.viewport enthält columns, rows und isFullscreen. Im Terminal und in der Desktop-App fehlt es, bis die App ihr Fenster gemessen hat. Dort ist sein Wert rows die Höhe des gesamten Fensters, nicht die Ihres Bereichs. In der VS Code-Erweiterung ist es immer vorhanden. Um einen Baum an seine Stelle anzupassen, lesen Sie im Hook die folgenden Props:
  • Breite eines Pane oder des Bands: Zeichnen Sie auf e.props.bodyColumns
  • Höhe eines Pane neben dem Transkript: Wenn e.props.placement den Wert 'dock' hat, ist e.props.scroll.bodyRows die Anzahl der Zeilen, die der Bereich für Ihren Baum hat
  • Höhe eines Pane über dem Prompt: Wenn e.props.placement den Wert 'inline' hat, wächst der Bereich mit Ihrem Baum bis zu einer Grenze, und bodyRows ist diese Grenze. Über das Feld rows von $.ui.open lässt sich eine andere Grenze anfordern.
Ein Baum, der höher als der Bereich ist, scrollt als Ganzes.

​
Elemente

Elemente sind die Bausteine eines Baums, den ein ui.render-Hook zurückgibt, und Sie erhalten sie über $.ui.resolve(e). Einen Baum aus Elementen erstellen zeigt die gängigen Elemente und wie das Terminal sie darstellt, und die Interface-Galerie enthält Screenshots der meisten. Ein Häkchen bedeutet, dass die App das Element darstellen kann. Weitere Regeln für Button:
  • action: benennt eine der eigenen Tastenkombinations-Aktionen von Claude Code, und die Tastenkombination des Benutzers dafür drückt die Schaltfläche, wenn diese Tastenkombination ein Akkord oder eine Taste mit Modifikator ist
  • Ziffern-Hotkeys im Band: Ein Ziffern-hotkey auf einer Schaltfläche im Band wird auch ausgelöst, wenn der Benutzer nur diese Ziffer in einen leeren Prompt eingibt und innehält
  • Ein eingeklapptes Band: Solange das Band eingeklappt ist, drückt weder eine action-Tastenkombination noch ein Hotkey eine Schaltfläche darin
  • Zwei Schaltflächen mit demselben Hotkey: Wenn zwei Schaltflächen in einer Zeichnung denselben hotkey angeben, erhält ihn die spätere
  • variant: primary oder secondary; jeder andere Wert löst einen Fehler aus. Im Terminal wird eine primary-Schaltfläche in der Akzentfarbe gezeichnet, sofern sie nicht plain ist.
  • role: dismiss kennzeichnet eine Schließen-Schaltfläche; jeder andere Wert löst einen Fehler aus. Führen Sie das Schließen in Ihrem onPress aus. In einem Band mit Text und einer Reihe von Schaltflächen kann die Desktop-App die erste dismiss-Schaltfläche der Reihe als eigenes Schließen-Steuerelement zeichnen. Das Terminal zeichnet die Schaltfläche so, wie es sie ohne role zeichnen würde.
Ein Button kann anstelle eines label auch children enthalten:
  • Was Children sein können: Strings und Text-Elemente, etwa ein Name gefolgt von einem abgeblendeten Detail oder ein farbiger Chip. Claude Code lehnt jedes andere Element innerhalb eines Button ab.
  • Benennung der Schaltfläche: Das label benennt die Schaltfläche und entspricht standardmäßig dem Text ihrer Children. Geben Sie einer Schaltfläche, deren Children nicht aus einem einzelnen String bestehen, einen key oder ein label.
  • Im Terminal: Die Children werden dort gezeichnet, wo das Label stehen würde, und ein Drücken an beliebiger Stelle darauf zählt als ein Drücken, sodass Sie jede Zeile einer Liste zu einer einzelnen Schaltfläche machen können
  • In der Desktop-App und der VS Code-Erweiterung: Die Schaltfläche zeichnet ihr label
Ein Button mit Children, die nicht aus einem einzelnen String bestehen, erfordert Claude Code v2.1.295 oder höher.
autoFocus akzeptiert bei jedem Steuerelement nur true; lassen Sie die Prop also weg, um es deaktiviert zu lassen. Die VS Code-Erweiterung ignoriert einige Element-Props und zeichnet das Element so, als hätten Sie sie weggelassen:
  • Box: position mit seinen top, left, right und bottom, alignSelf, borderDimColor und hover
  • Text: size, mono, tabular und hover
  • Button: hotkey, plain, autoFocus, action und hover, sodass der Benutzer eine Schaltfläche dort per Klick drückt oder mit der Eingabetaste, sobald sie den Fokus hat. Die Erweiterung ignoriert außerdem variant und role.
  • Code: language, path, startLine, format und wrap, sodass Code ohne Farben oder Zeilennummern gezeichnet wird und ein Block mit format: 'diff' den Rohtext des Diffs anzeigt
  • Input und Select: autoFocus sowie rows bei einem Input
  • Svg: isInteractive

​
Rahmenstile für Box

Um einen Rahmen um eine Box zu zeichnen, setzen Sie deren borderStyle auf einen dieser Namen, etwa borderStyle: 'round'. Jede Zeile gibt an, was das Terminal für diesen Namen zeichnet, und zeigt die Oberkante des Rahmens. Eine Box, deren borderStyle einen anderen Namen angibt, etwa 'rounded', wird ohne Rahmen gezeichnet.

​
Abstandsstufen für Box

Die Abstands-Props von Box sind gap, columnGap, rowGap, padding, margin sowie die Formen von padding und margin für eine Seite oder eine Achse, etwa paddingX und marginTop. Jede nimmt eine Anzahl von Terminal-Zellen wie gap: 1 oder einen Stufennamen wie gap: 'md' an. Im Terminal und in der VS Code-Erweiterung entspricht jede Stufe dieser Anzahl von Zellen: Wenn Sie gap, padding oder margin auf eine Stufe setzen, gilt die Stufe gleichzeitig horizontal und vertikal. Im Terminal und in der VS Code-Erweiterung bedeutet padding: 'md' beispielsweise zwei Zellen auf jeder Seite und eine Zeile darüber und darunter. Stufennamen erfordern Claude Code v2.1.299 oder höher. In einer früheren Version wird ein Baum, der einen Stufennamen verwendet, nicht gezeichnet.

​
Typografie-Props für Text

Setzen Sie size, weight, mono oder tabular auf einem Text, um die App, die Ihren Baum zeichnet, um eine Textgröße, eine Schriftstärke, eine Festbreitenschrift oder Ziffern gleicher Breite zu bitten. Bevor Sie sich auf eine Prop verlassen, prüfen Sie, was das Terminal und die VS Code-Erweiterung damit tun. Wenn eine App eine von Ihnen gesetzte Prop ignoriert, wird Ihr Baum dort trotzdem gezeichnet, mit dem Text so, als hätten Sie diese Prop weggelassen. Diese vier Props erfordern Claude Code v2.1.299 oder höher. In einer früheren Version wird ein Baum, der size, weight, mono oder tabular setzt, nicht gezeichnet.

​
bold durch weight ersetzen

bold auf einem Text ist zugunsten von weight veraltet, funktioniert aber weiterhin. Um es auf einem Text ohne weight zu ersetzen, ändern Sie bold: true in weight: 'semibold', um unter Claude Code v2.1.299 oder höher dasselbe Ergebnis zu erhalten. In einer Version vor v2.1.299 wird ein Baum, der weight setzt, nicht gezeichnet. Wenn Sie auf einem Text sowohl bold als auch weight setzen, hat bold keine Wirkung.

​
Limits

Hooks und Aufrufe der Mods-API unterliegen Zeit- und Größenlimits. Claude Code überspringt einen Hook, der ein Zeitlimit überschreitet. Ein Baum, der das Limit für Verschachtelung, Elemente, Raster-Zellen oder Image-Bytes überschreitet, wird nicht gezeichnet.

​
Einstellungen und Umgebungsvariablen

Dies sind die Einstellungen und Umgebungsvariablen, die sich auf Mods auswirken. Die Spalte „Ort“ gibt an, aus welcher Einstellungsdatei oder Umgebung die jeweilige Einstellung gelesen wird: sec-default@builtin ist ein in Claude Code integrierter Wächter, der in /plugin und im Debug-Log als cc-plugin-sec-default aufgeführt wird. Er wird vor jedem Mod geladen, den eine Person auf einem Rechner mit verwalteten Einstellungen installiert, oder in einer Sitzung, deren Anmeldedaten aus einem Team- oder Enterprise-/login stammen. Wenn das verwaltete prependPlugins gesetzt ist, wird der Wächter nur geladen, wenn diese Liste ihn aufführt, und zwar an der aufgeführten Position. Sein Quellcode befindet sich im Verzeichnis mods/sec-default des Claude Code-Repositorys.

​
Befehle

Mit diesen Befehlen und Flags laden, prüfen und testen Sie einen Mod. Die claude-Befehle werden in Ihrer Shell ausgeführt, die /-Befehle im Prompt von Claude Code. In der Tabelle steht <directory> für einen Pfad, den Sie eingeben, wie in claude plugin validate ./first-mod. Eckige Klammern kennzeichnen ein optionales Argument.