SpyBara
Go Premium

plugins/mods/reference.md 2026-10-26 22:57 UTC to 2026-10-27 22:59 UTC

This page contains 23 additions and 10 deletions.

2026
Fri 2 22:59 Sat 3 23:57 Sun 4 23:58 Tue 6 23:59 Wed 7 23:59 Thu 8 22:58 Fri 9 23:02 Sat 10 23:01 Sun 11 23:57 Wed 14 22:58 Thu 15 23:58 Fri 16 22:59 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Mon 26 22:57 Tue 27 22:59

Mods-Referenz

Vollständige Referenz für Claude Code-Mods: Aufbau des Hooks-Moduls, Events, Methoden der Mods-API, Render-Stellen, Elemente nach Oberfläche, Limits und Einstellungen.

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.

[!NOTE]

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:

Datei Erforderlich Inhalt
.claude-plugin/plugin.json Ja Das Manifest des Plugins. Mods fügen keine erforderlichen Felder hinzu.
hooks/hooks.json Ja modules: ein Array mit einem Pfad zum Hooks-Modul, relativ zu dieser Datei, wie in "modules": ["./register.js"]. Kann unter hooks auch Einstellungs-Hooks enthalten.
Das Hooks-Modul, zum Beispiel hooks/register.js Ja Der Einstiegspunkt des Mods. Exportiert register(on, options). Mit der Endung .js, .mjs, .cjs, .jsx, .ts, .mts, .cts oder .tsx. Ein ES-Modul.
types/index.d.ts, sofern types im Manifest keinen anderen Pfad angibt Wenn der Mod $.state verwendet oder der Mods-API einen Namespace hinzufügt Deklariert PluginState-Werte und jeden Namespace, den der Mod hinzufügt. Um types im Manifest wegzulassen, benötigen Sie v2.1.299 oder höher.
Dateien, deren Namen auf .test.ts oder .test.tsx enden Nein Tests, die claude plugin test ausführt

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.

Argument Was es ist
$ Die Mods-API: jede Methode in Methoden der Mods-API. Schreiben Sie jeden Aufruf vollständig aus, zuerst den Namespace, dann die Methode, wie in $.fs.read('notes.md').
e Die Eingabe des Events als tief eingefrorene einfache Daten. Um sie zu ändern, übergeben Sie eine Kopie an next.
next(e) Der nächste Handler, wie bei Middleware. Führt die Hooks nach diesem aus, dann das Verhalten von Claude Code. Wird zum Ergebnis des Events aufgelöst.
next.signal Ein AbortSignal, das abbricht, wenn das Event verworfen wird
next.origin { plugin, tier } desjenigen, der das Event ausgelöst hat. Claude Code selbst ist { plugin: 'engine', tier: 'core' }. Der tier eines Mods ist seine Prioritätsgruppe in der Reihenfolge, in der Mods ausgeführt werden: prepend, user, append oder builtin.
next.budget Das Zeitlimit des Hooks in Millisekunden: next.budget.ms ist das gesamte Limit, und next.budget.remainingMs ist die aktuell verbleibende Zeit
next.to(e, tier) Springt zu einem späteren Tier, nämlich append, builtin oder core. next.to(e, 'append') überspringt die Mods, die ein Benutzer installiert hat. Nur ein Mod in prependPlugins oder appendPlugins kann es aufrufen.
next.error Nur in einem .catch-Handler. kind ist throw oder timeout, wenn der Hook fehlgeschlagen ist, und message ist der Text des Fehlers. kind ist re-entry, wenn der Hook übersprungen wurde, weil das Event aus einem Aufruf der Mods-API stammte, den dieser Hook oder der Code Ihres Mods außerhalb seiner Hooks ausgeführt hat. re-entry erfordert Claude Code v2.1.292 oder höher.
next.error.cause Nur gesetzt, wenn kind gleich re-entry ist. rewritten, wenn ein tool.call- oder PreToolUse-Hook den Aufruf der Mods-API geändert hat, aus dem das Event stammte, oder ein agent.spawn-Hook einen durch diesen Aufruf gestarteten Agenten geändert hat. lent, wenn eine Methode, die ein anderer Mod zur Mods-API hinzufügt, dieses Event ausgelöst hat, sofern nicht auch rewritten zutrifft. lent erfordert Claude Code v2.1.292 oder höher und rewritten v2.1.300 oder höher.
next.called Nur in einem .catch-Handler. true, wenn der Hook next aufgerufen hatte.

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:

Event Wird ausgelöst, wenn Ein Hook kann zurückgeben
tool.call Ein Tool gleich ausgeführt wird next(e), { deny: reason } oder { result }
tool.check Claude Code entscheidet, ob ein Tool-Aufruf ausgeführt werden darf, nach den Hooks tool.call und PreToolUse. next(e) wird zu der Entscheidung aufgelöst, zu der die Regeln, der Berechtigungsmodus und diese Hooks gelangt sind. next(e) oder { decision }, wobei decision auf allow, ask oder deny gesetzt ist, mit einem optionalen reason
tool.describe Einmal für jedes Tool, wenn seine Beschreibung zum ersten Mal an Claude gesendet wird. Ein zweites Mal für ein MCP-Tool, wenn Claude es über die Tool-Suche lädt, wobei e.description auf den Text gesetzt ist, den Claude für das geladene Tool liest. { description }, optional mit isDeferred auf true gesetzt, um das Tool hinter die Tool-Suche zu stellen, oder auf false, um es vorab zu laden

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:

Event Wird ausgelöst, wenn Ein Hook kann zurückgeben
prompt.submit Ein Prompt abgeschickt wird next({ ...e, text }), next({ ...e, context }) oder { drop: reason }
prompt.fill, prompt.suggest Text gleich als Entwurf oder als abgeblendeter Vorschlag in das Eingabefeld eingefügt wird next(e) mit geändertem Text
prompt.edit Der Benutzer das Eingabefeld bearbeitet next(e)
prompt.autocomplete Der Benutzer im Eingabefeld tippt und an der Cursorposition ein Wort endet. e.token ist dieses Wort. Claude Code wartet nicht auf den Hook: Seine eigenen Autovervollständigungszeilen werden zuerst angezeigt. { suggestions }, eine Liste von { text, label, description }-Zeilen, die unter denen von Claude Code angezeigt werden. Das Auswählen einer Zeile schreibt ihren text über das Wort.
prompt.compose Claude Code einen System-Prompt rendert { sections }, eine Liste von { id, text, scope } in der Reihenfolge, in der sie gesendet werden
prompt.section Einmal für jeden benannten Abschnitt des System-Prompts. e.name ist die id des Abschnitts in prompt.compose. { text } oder { text: null }, um den Abschnitt auszulassen
prompt.context Einmal pro Konversation, für den Kontext, der mit der ersten Nachricht gesendet wird { blocks }
prompt.attachment Claude Code eine eigene Nachricht für Claude hinzufügt, etwa eine Erinnerung. e.type benennt die Art, und für die Arten, die die Typen deklarieren, enthält e.detail die Fakten, aus denen der Text geschrieben wurde. { text } oder { text: null }, um sie auszulassen
prompt.mention Claude Code gleich eine Datei liest, die in einem Prompt per @ erwähnt wird. Erfordert Claude Code v2.1.290 oder höher. next({ ...e, path }), um eine andere Datei zu lesen, oder { deny: reason }
skill.prompt Der Text eines Skills für Claude expandiert wird { text }
attribution.text Claude Code den Attributionstext für einen Commit oder Pull Request erstellt { text }

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:

Feld Typ Was es enthält
e.source string Wer den Skill bereitstellt: policySettings, userSettings oder projectSettings für einen Skill am Unternehmens-, persönlichen bzw. Projekt-Speicherort. Andere Quellen liefern ein Wort wie plugin, mcp, syncedSkills oder built-in.
e.pluginName string Der Name des Plugins, für einen Skill, dessen e.source gleich plugin ist
e.path string Der absolute Pfad der SKILL.md-Datei des Skills oder seiner .md-Datei bei einem Skill, der als Befehlsdatei geschrieben ist. Nicht vorhanden, wenn der Skill auf diesem Rechner keine Datei hat, wie bei einem integrierten Skill.
e.frontmatter object Das Frontmatter der Datei des Skills als einfache Daten
e.frontmatterProblem string Der Grund, warum in e.frontmatter das Frontmatter der Datei oder einer seiner Schlüssel fehlt, wie in is a list or a single value, not a table. Nicht vorhanden, wenn e.frontmatter das gesamte Frontmatter enthält oder der Skill keines hat.

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

Event Wird ausgelöst, wenn Ein Hook kann zurückgeben
command.run Ein Befehl gleich ausgeführt wird { text }, {} oder next(e)
command.describe Einmal für jeden Befehl, für die Befehlsliste { description, argumentHint, isHidden }
config.set Eine /config-Zeile sich gleich ändert next({ ...e, value }) oder { deny: reason }
config.describe Einmal für jede /config-Zeile { label, description, isHidden }
settings.read Ein Mod $.settings.read aufruft oder Claude Code die zusammengeführten Einstellungen der Sitzung erstellt. Erfordert Claude Code v2.1.304 oder höher beim eigenen Lesevorgang von Claude Code und für e.layers next(e), { value } oder { deny: reason }

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:

Event Wird ausgelöst, wenn Ein Hook kann zurückgeben
turn.start Ein Turn beginnt next(e)
turn.step Eine Anfrage gleich an das Modell gesendet wird yield* next(e) oder next({ ...e, model }), next({ ...e, effort })
turn.complete Ein Turn beendet wurde next(e) oder { text }, um eine Zeile unter der Antwort anzuzeigen

Sitzung

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

Event Wird ausgelöst, wenn Ein Hook kann zurückgeben
session.start Einmal für jeden geladenen Mod, vor dem ersten Prompt, und erneut nach einem Neuladen dieses Mods. Nicht nach /clear, /resume oder /branch. next(e)
session.end Die Sitzung endet oder /clear, /resume oder /branch ausgeführt wird. e.reason ist clear, resume, logout, prompt_input_exit oder other. /branch meldet resume. next(e)
session.compact Die Konversation gleich komprimiert wird { skip: reason }
session.receive, session.send Eine Nachricht von einem anderen Agenten oder einer anderen Sitzung eintrifft oder gleich dorthin gesendet wird. Siehe Nachrichten zwischen Sitzungen senden und empfangen. { consumed: reason } für receive, { isDelivered: false, reason } für send
session.append Einmal für jede Zeile, die die Konversation behält, etwa ein Prompt, ein Antwortblock, ein Tool-Ergebnis oder ein Hinweis, bevor sie gespeichert wird next({ ...e, message }) mit einem geänderten message.content, um die Textblöcke der Zeile oder den content eines darin enthaltenen tool_result-Blocks umzuschreiben
session.attach, session.detach Eine andere App sich mit der Sitzung verbindet oder die Verbindung trennt next(e)
session.measure Nach jedem Turn und wenn sich der genutzte Prozentsatz eines Planlimits ändert next(e)

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:

Event Wird ausgelöst, wenn Ein Hook kann zurückgeben
agent.offer Claude ein Subagenten-Typ angeboten wird { isOffered: false }, um ihn zurückzuhalten
agent.spawn Ein Subagent oder ein Teammitglied eines Agent-Teams gleich startet. Bei einem Teammitglied ist e.isTeammate gleich true. next({ ...e, model }), um sein Modell zu wählen, oder { deny: reason }

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:

Event Wird ausgelöst, wenn
ui.render Eine Render-Stelle gleich gezeichnet wird
ui.resolve Mods geladen werden, einmal für jede App, Render-Stelle und jeden Mod. Das Ergebnis ist die Element-Tabelle, die $.ui.resolve(e) liest.
ui.press, ui.input, ui.select Ein Button, Input oder Select, das ein Mod gezeichnet hat, verwendet wird
ui.focus, ui.scroll Sich das fokussierte Steuerelement oder die Scrollposition eines Bereichs oder des Bands gleich ändert
ui.close Ein Bereich gleich geschlossen wird. e.id ist der Bereich und e.origin.kind ist plugin, person oder unload.
ui.message Ein Client-Element Daten an seinen Mod sendet
ui.fault Ein Client-Element, das Ihr Mod gezeichnet hat, nicht geladen, gezeichnet oder ausgeführt werden konnte. e.phase ist load, render oder run, und e.reason ist die Fehlermeldung. Erfordert Claude Code v2.1.289 oder höher.

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:

Event Wird ausgelöst, wenn Ein Hook kann zurückgeben
plugin.register Ein Hooks-Modul gleich geladen wird. e.uses listet seine Events, Mods-API-Aufrufe, Umgebungsvariablen und seinen Zustand auf, so wie claude plugin validate sie ausgibt. Jeder Aufruf wird ohne das Präfix $. geschrieben, etwa fs.read. { refuse: reason }
engine.create Die Mods-API für diesen Mod aufgebaut wird Eine geänderte Mods-API, um einen Namespace hinzuzufügen. Ein Mod außerhalb der Stufe user kann auch einen zurückhalten.

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:

Event Wird ausgelöst, wenn Ein Hook kann zurückgeben
telemetry.log, telemetry.mark Ein Telemetriedatensatz gleich protokolliert oder eine Nutzung einer Funktion markiert wird. Geben Sie in einem Mod, den Sie installieren, einem Telemetrie-Hook den Filter { to: 'collector' }, wie in on('telemetry.log', { to: 'collector' }, hook). Ohne den Filter besteht der Mod claude plugin validate nicht. * passt nicht auf diese Events. next(e) oder { deny: reason }

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.

Namespace Methoden
$.plugin name, root: Name und Verzeichnis dieses Plugins
$.ui resolve, invalidate, open, close, panes, focus, scroll, toast, notify, status, log, notice, ask, copy, selection, blit
$.command register, run, list
$.tool register, call, check, list
$.agent register, spawn, list. list() gibt die Subagenten und Teammitglieder dieser Sitzung zurück, jeweils mit einem status von pending, running, waiting, idle, completed, failed oder killed, wobei idle und waiting Claude Code v2.1.289 oder neuer erfordern.
$.model complete, fork, classify
$.prompt submit, read, fill, suggest, compose. Claude liest Text aus submit({ text }) nach einem Satz, der Ihren Mod als Absender nennt. submit({ text, asUser: true }) sendet den Text als eigene Worte des Benutzers, ohne diesen Satz.
$.turn abort
$.session messages, cwd, root, model, turns, id, repo, surfaces, usage, version, compact, send, append, authorize. usage() gibt { startedAt, context, rateLimits, cost } zurück: context enthält tokens, window und percent, und rateLimits ist eine Liste von { kind, percentUsed, resetsAt }.
$.config list, set
$.settings read
$.env get, set
$.fs read, write, list, exists, stat, ancestors. write ist nicht atomar: Es ersetzt den Inhalt der Datei direkt, sodass ein anderer Prozess eine teilweise geschriebene Datei lesen kann. Speichern Sie Daten, die von mehreren Sitzungen geändert werden, in $.store.
$.store get, set, delete, keys. Ein Key-Value-Speicher, den alle Sitzungen auf dem Rechner gemeinsam nutzen. Siehe Aus mehr als einer Sitzung speichern.
$.state Reaktiver Zustand: get, set, mit den Hilfsfunktionen atom, read, update, derive und memberOf, importiert aus claude-code
$.clock now, sleep, after, every
$.http fetch
$.process run, spawn
$.mcp call, connect. connect(server) verbindet einen MCP-Server, den das Manifest Ihres eigenen Plugins aufführt.
$.audio play, speak
$.telemetry log, mark. Ein Eintrag wird nur gesendet, wenn Claude Code oder ein integrierter Mod den Aufruf ausführt.

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.

Stelle e.props e.requestId Gerendert in
Pane title, isFocused, bodyColumns, placement, scroll, view Die id des Bereichs Terminal, Desktop, VS Code
AbovePrompt hasSurvey, isWorking, maxRows, bodyColumns, scroll, view Eine Instanz Terminal, Desktop
UserMessage text, origin, isExpanded sowie je nach Herkunft task oder from Die Nachrichten-ID Terminal, Desktop, VS Code
AssistantMessage Der Text der Antwort Die Nachrichten-ID Terminal, Desktop, VS Code
ToolUse, ToolResult, ToolGroup Name, Eingabe und Ergebnis des Tools Die ID des Tool-Aufrufs Terminal, Desktop, VS Code
CommandOutput command, text Die Nachrichten-ID Terminal, Desktop
AskUserQuestion Die Frage und die Optionen Die ID des Tool-Aufrufs Terminal, Desktop, VS Code
ToolProgress kind Die ID des Tool-Aufrufs Terminal
Spinner word, message, suffix, mode Die ID des Agenten Terminal, Desktop, VS Code
TurnDuration word, durationMs Die Nachrichten-ID Terminal
InfoNotice text, command Die Nachrichten-ID Terminal
SessionMode modes Eine Instanz Terminal, Desktop
PromptHint isDraft, isWorking, hint Eine Instanz Terminal, Desktop

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.

Element Wichtigste Props Terminal Desktop VS Code
Box key, Flex-Layout, gap, padding, margin, width, height, minWidth, minHeight, borderStyle, borderColor, borderDimColor, backgroundColor, position, top, left, right, bottom, overflow, display, hover ✓ ✓ ✓
Text color, backgroundColor, bold, italic, underline, strikethrough, dimColor, inverse, wrap, size, weight, mono, tabular, hover ✓ ✓ ✓
Button key, label, children, onPress, hotkey, plain, dimColor, autoFocus, action, variant, role, hover ✓ ✓ ✓
Link href, label. Siehe Grenzen. ✓ ✓ ✓
Code source, language, path, startLine, format, wrap ✓ ✓ ✓
Markdown text, key, dimColor, onLinkPress, pressableLinks ✓ ✓ ✓
Input key, label, placeholder, value, submitLabel, rows, onSubmit, onInput, autoFocus ✓ ✓ ✓
Select key, label, options, value, onSelect, autoFocus ✓ ✓ ✓
Svg eine source mit SVG-Markup bis zu 131.072 Zeichen, alt-Text, width, height und isInteractive ✓ ✓
Client module, key, props, width, height, flexGrow ✓ ✓
Raster key, columns bis zu 512, rows bis zu 256, cells. Siehe Ein Raster farbiger Zellen zeichnen. ✓
Image key, eine source wie PNG- oder RGBA-Bytes bis zu 2 MiB oder ein Dateipfad, columns und rows bis zu 255 sowie alt-Text. Siehe welche Terminals es darstellen. ✓

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

[!NOTE]

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.

borderStyle Was das Terminal zeichnet Oberkante
'single' Dünne Linien mit eckigen Ecken ┌──┐
'double' Doppelte Linien ╔══╗
'round' Dünne Linien mit abgerundeten Ecken ╭──╮
'bold' Dicke Linien ┏━━┓
'singleDouble' Dünne Linien oben und unten, doppelte Linien an den Seiten ╓──╖
'doubleSingle' Doppelte Linien oben und unten, dünne Linien an den Seiten ╒══╕
'classic' Die ASCII-Zeichen +, - und | +--+
'arrow' Pfeile, die in die Box zeigen ↘↓↓↙
'dashed' Gestrichelte Linien mit leeren Ecken ╌╌
'quote' Ein Balken, ▎, an der linken Seite entlang und leere Zellen an den anderen drei Seiten Leer

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:

Stufe Zellen horizontal Zellen vertikal
'xs' 1 0
'sm' 1 0
'md' 2 1
'lg' 3 1
'xl' 4 2

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.

Prop Werte Im Terminal In der VS Code-Erweiterung
size 'caption', 'footnote', 'body', 'heading' oder 'title' Ignoriert: Das Terminal hat nur eine Textgröße Ignoriert
weight 'regular', 'medium', 'semibold' oder 'bold' semibold und bold werden als fetter Text gezeichnet semibold und bold werden als fetter Text gezeichnet
mono true, um die Festbreitenschrift der App anzufordern Ignoriert: Das Terminal verwendet immer eine Festbreitenschrift Ignoriert, sodass der Text die eigene Schrift der Erweiterung behält
tabular true, um Ziffern gleicher Breite anzufordern, damit eine Zahl, die sich an Ort und Stelle aktualisiert, oder eine Zahlenspalte ausgerichtet bleibt Ignoriert: Die Ziffern des Terminals sind bereits eine Zelle breit Ignoriert

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.

Limit Wert
Eigene Ausführungszeit eines Hooks für ein Ereignis, ohne die Zeit innerhalb von next oder eines Aufrufs der Mods-API außer $.clock.sleep 10 Sekunden bzw. 50 Millisekunden für einen prompt.edit-Hook
Ausführungszeit eines .catch-Handlers 1 Sekunde
Alle session.end-Hooks zusammen So lange wie das Zeitbudget des SessionEnd-Hooks, 1,5 Sekunden, sofern Sie es nicht ändern, gemessen ab dem Zeitpunkt, an dem die SessionEnd-Hooks aus Ihren Einstellungen abgeschlossen sind
$.process.run-Timeout Standardmäßig 30 Sekunden, höchstens 10 Minuten
$.process.run stdout und stderr Jeweils 4 MiB. isStdoutTruncated bzw. isStderrTruncated ist true, wenn eine der Ausgaben abgeschnitten wurde.
$.model.complete maxTokens Standardmäßig 1024, bis zu 64.000 oder das Ausgabelimit des Modells
$.fs.read und $.fs.write 4 MiB für eine Datei
Request-Body eines $.http.fetch-Aufrufs 4 MiB, gezählt in Zeichen. Ein Aufruf mit einem größeren Body wird abgelehnt.
Response-Body eines $.http.fetch-Aufrufs 4 MiB. text enthält die ersten 4 MiB, der Rest wird nicht gelesen. Wenn der Content-Length-Header mehr angibt, wird der Aufruf stattdessen abgelehnt, mit einem Grund, der auf is over the 4194304-byte limit endet, außer wenn die letzte Anfrage nach etwaigen Weiterleitungen die Methode HEAD verwendet. Die Ausnahme für HEAD erfordert Claude Code v2.1.296 oder höher.
Ein $.http.fetch-Aufruf, einschließlich Weiterleitungen und Body 30 Sekunden
Weiterleitungen, denen ein $.http.fetch-Aufruf folgt 5
drop-Grund eines Hooks oder deny-Grund von config.set 4.096 Zeichen. Das Ende eines längeren Grundes wird abgeschnitten, und das Drop bzw. Deny gilt weiterhin. Das Abschneiden erfordert Claude Code v2.1.292 oder höher; in früheren Versionen schlägt der Hook stattdessen fehl.
Text in einem Baum Die ersten 100.000 Zeichen werden gezeichnet
language oder path eines Code, value einer Select-Option oder module eines Client 10.000 Zeichen. Ist einer dieser Werte länger, schlägt der ui.render-Hook, der ihn zurückgegeben hat, fehl.
href eines Link 2.048 Zeichen. Ist er länger, schlägt der ui.render-Hook, der ihn zurückgegeben hat, fehl.
Verschachtelungstiefe eines Baums 32 Ebenen unterhalb des Wurzelelements
Elemente und Text-Kindelemente in einem Baum 20.000
Raster-Zellen in einem Baum, jeweils columns mal rows jedes Raster 262.144
PNG- oder RGBA-Bytes aller Image-Elemente in einem Baum 2 MiB
$.store Insgesamt 4 MiB JSON
$.session.messages() Die neuesten 4.096 Einträge
Neuzeichnungen durch $.ui.invalidate('ui.render') Gedrosselt auf 10 pro Sekunde bzw. 30 im Terminal für den sichtbaren Bereich, das erweiterte Band und die Hinweiszeile unter dem Eingabefeld. Früher eingehende Aufrufe werden zusammengefasst.
$.ui.toast Wird 4 Sekunden lang angezeigt, sofern Sie nicht { timeoutMs } übergeben. Im klassischen Renderer kann ein neuerer Toast eines Mods den Platz seines älteren Toasts einnehmen, der gerade angezeigt wird oder auf die Anzeige wartet.
Ein Bereich, der ohne Anforderung durch den Benutzer geöffnet wird Wird ab 144 Terminalspalten platziert, ab 110, nachdem der Benutzer ihn einmal geöffnet hat
Verschachtelungstiefe der Argumente eines Aufrufs der Mods-API 28.000 Ebenen. Darüber hinaus wird der Aufruf mit einer Meldung abgelehnt, die auf nesting deeper than 28000 levels is not supported endet. Erfordert Claude Code v2.1.299 oder höher.
Verschachtelungstiefe eines geänderten Ereignisses, das an next übergeben wird, außerhalb von asynchronen Generator-Hooks wie einem Hook auf turn.step 28.000 Ebenen. Darüber hinaus wird next mit einer Meldung abgelehnt, die auf nesting deeper than 28000 levels is not supported endet. Erfordert Claude Code v2.1.299 oder höher.
Verschachtelungstiefe des Rückgabewerts eines Hooks, außerhalb von ui.render, ui.resolve und asynchronen Generator-Hooks 28.000 Ebenen. Darüber hinaus wird das Ergebnis des Hooks zurückgewiesen, und der Hinweis, der dies meldet, enthält nesting deeper than 28000 levels is not supported. Erfordert Claude Code v2.1.299 oder höher.
Geltungsbereiche wie Funktionen, Blöcke und Schleifen, die in einer Datei eines Hooks-Moduls ineinander verschachtelt sind 2.000
Namen von Befehlen, Tools, Subagent-Typen und Bereichen Buchstaben, Ziffern, _ und -, bis zu 64 Zeichen
Ein Test von claude plugin test 5 Sekunden, sofern der Test nicht timeoutMs festlegt

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:

Name Ort Funktion
CLAUDE_CODE_PLUGIN_DIRS Umgebung oder env in ~/.claude/settings.json Plugin-Verzeichnisse, die wie mit --plugin-dir geladen werden, für Anwendungen, denen Sie kein Flag übergeben können. Absolute Pfade, getrennt durch : bzw. unter Windows durch ;.
CLAUDE_CODE_PLUGIN_DIR_WATCH Umgebung 1 bewirkt, dass eine lang laufende nicht-interaktive Sitzung --plugin-dir-Mods beim Speichern neu lädt
prependPlugins, appendPlugins Verwaltete Einstellungen. Benutzereinstellungen nur auf einem Rechner ohne verwaltete Einstellungen und in einer Sitzung, deren Anmeldedaten nicht aus einem Team- oder Enterprise-/login stammen. Listen von Plugin-IDs, etwa acme-guard@acme-tools. Mods in prependPlugins laufen vor jedem Mod, den ein Benutzer installiert, und Mods in appendPlugins danach, jeweils in der aufgeführten Reihenfolge. Siehe Die Reihenfolge, in der Mods ausgeführt werden.
allowManagedModsOnly Verwaltete Einstellungen, als Option des integrierten Wächters Nur Mods, die als Mods Ihrer Organisation gelten, sowie die in Claude Code integrierten Mods führen ihre Hooks aus. Die Einstellungs-Hooks der Benutzer laufen weiter.
allowModsToOverrideDenyRules Verwaltete Einstellungen, als Option des integrierten Wächters Erlaubt einem von einem Benutzer installierten Mod, einen Tool-Aufruf zu genehmigen, den eine deny-Regel ablehnt
allowManagedHooksOnly Verwaltete Einstellungen Blockiert Hooks und installierte Mods, die nicht von Ihrer Organisation stammen. Siehe was weiterhin ausgeführt wird.
disableAllHooks Jede Einstellungsdatei In verwalteten Einstellungen wird kein Mod und kein Hook aus einem installierten Plugin ausgeführt. In Ihren eigenen Einstellungen läuft weiterhin, was Ihre Organisation verwaltet. Siehe disableAllHooks.
disableSideloadFlags Verwaltete Einstellungen Lehnt --plugin-dir und --plugin-url beim Start ab
pluginConfigs Benutzer- oder verwaltete Einstellungen Enthält userConfig-Werte für einen Mod, mit der ID des Plugins als Schlüssel, etwa acme-guard@acme-tools, oder mit seinem Namen und @inline, etwa first-mod@inline, für einen mit --plugin-dir geladenen Mod

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.

Befehl Funktion
/plugin Zeigt unter seinen Tabs eine Zeile wie 1 mod active · first-mod an, wenn ein nicht integrierter Mod geladen wurde
claude plugin validate <directory> Liest das Manifest und das Hooks-Modul eines Plugins und meldet Fehler, die behandelten Events sowie die Aufrufe der Mods-API. --strict behandelt Warnungen als Fehler, und --json gibt einen maschinenlesbaren Bericht aus.
claude plugin test [directory] Führt jede Datei unter dem Verzeichnis aus, deren Name auf .test.ts oder .test.tsx endet, bzw. im aktuellen Verzeichnis, wenn Sie keines angeben. Beendet sich mit Status 1, wenn ein Test fehlschlägt.
claude --plugin-dir <directory> Lädt ein Plugin-Verzeichnis für eine Sitzung und lädt dessen Hooks-Modul beim Speichern neu. Wiederholen Sie das Flag, um mehrere zu laden.
/reload-plugins Lädt Plugins neu, wenn Sie den Befehl ausführen