SpyBara
Go Premium

plugins/loading.md 2026-09-28 22:59 UTC to 2026-09-29 05:02 UTC

This page contains 424 additions and 0 deletions.

2026
Tue 29 06:02

Plugin-Ladeverweis

Verfolgen Sie, von wo Claude Code jedes Plugin lädt, welche Einstellungsdatei entscheidet, ob es geladen wird, und warum ein Update nichts geändert hat.

Verwenden Sie diese Seite, wenn ein Plugin nicht geladen wurde, eine andere Kopie als erwartet geladen wurde oder ein Update nicht aufgegriffen wurde, und Sie sehen möchten, welche Quelle, Einstellungsbereich oder Datei auf der Festplatte dies entschieden hat. Sie zeigt die Regeln, die Claude Code anwendet, wenn eine Sitzung startet und jedes Mal, wenn Sie /reload-plugins ausführen. Sie können Claude auch bitten, diese Seite zu lesen und Ihr Setup zu diagnostizieren.

Beginnen Sie mit Überprüfen Sie, welche Phase ein Plugin erreicht hat für die drei Phasen, die ein installiertes Plugin durchläuft, oder gehen Sie zu dem Abschnitt, der dem entspricht, was Sie sehen:

Überprüfen Sie, welche Phase ein Plugin erreicht hat

Ein enabledPlugins-Eintrag wird zu einem Plugin, das Sie in Phasen verwenden können: Ihre Einstellungen deklarieren es, Claude Code ruft es auf die Festplatte ab, und die laufende Sitzung lädt es. Wenn sich ein Plugin nicht so verhält, wie eine Einstellungsdatei vermuten lässt, überprüfen Sie, welche Phase es erreicht hat:

  • Deklariert, in Einstellungen: enabledPlugins gibt an, welche Plugins aktiviert sein sollten, und extraKnownMarketplaces gibt an, welche Marktplätze vorhanden sein sollten. Wenn Sie claude plugin marketplace add ausführen, schreibt Claude Code den Marktplatz sowohl in extraKnownMarketplaces in Ihren Benutzereinstellungen als auch auf die Festplatte
  • Abgerufen, auf der Festplatte unter ~/.claude/plugins/: die Aufzeichnungen darüber, was Claude Code abgerufen hat, und die abgerufenen Dateien selbst:
    • known_marketplaces.json zeichnet jeden Marktplatz auf, den Claude Code abgerufen hat, mit seiner source, installLocation, lastUpdated und autoUpdate. Es gibt eine known_marketplaces.json pro Benutzer, daher ist ein Marktplatz, den Sie in einem Projekt hinzufügen, in jedem Projekt verfügbar
    • installed_plugins.json zeichnet jede Installation mit ihrem scope, installPath und version auf
    • cache/ enthält die Plugin-Dateien
  • Geladen, in der laufenden Sitzung: die Plugin-Menge, die Claude Code beim Start oder beim letzten /reload-plugins geladen hat. Änderungen an Einstellungen oder auf der Festplatte erreichen diese Ebene erst, wenn Sie /reload-plugins ausführen oder eine neue Sitzung starten. Deshalb endet claude plugin update mit Restart to apply changes. und Hintergrund-Updates fordern Sie mit Run /reload-plugins to apply auf

Plugins und Marktplätze, die beim Sitzungsstart nicht auf der Festplatte vorhanden sind

Plugins werden beim Sitzungsstart aus installed_plugins.json und dem Cache geladen, ohne das Netzwerk zu nutzen. Nach dem Sitzungsstart überprüft Claude Code die deklarierten Marktplätze im Hintergrund:

  • Ein Marktplatz, den Einstellungen deklarieren, aber known_marketplaces.json fehlt: Claude Code klont ihn, lädt dann Plugins neu und lädt aktivierte Plugins herunter, die noch nicht zwischengespeichert sind
  • Ein deklarierter Marktplatz, dessen Quelle sich in den Einstellungen geändert hat: Claude Code ruft ihn von der neuen Quelle ab und zeigt Plugins changed. Run /reload-plugins to activate. an

Ein aktiviertes Plugin, das von keinem der beiden Pfade abgerufen wurde und das kein verwendbares Cache-Verzeichnis hat, zeigt Plugin "<name>" not cached at <path> auf der Registerkarte /plugin Errors an, und claude plugin list fügt — run /plugin to refresh auf derselben Zeile hinzu. Für die Behebung siehe Plugin "<name>" not cached at <path>.

Finden Sie heraus, von wo ein Plugin kam

Jedes Plugin hat eine ID der Form <name>@<origin>, die Sie in Einstellungsdateien und in claude plugin list --json sehen. Der Teil nach @ sagt Ihnen, wo Claude Code das Plugin gefunden hat:

ID endet mit Wie das Plugin dorthin kam Wie Sie es aktivieren oder deaktivieren
@<marketplace> Sie haben es von einem Marktplatz installiert, den Sie hinzugefügt haben "<name>@<marketplace>": true oder false unter enabledPlugins in einer Einstellungsdatei
@inline Sie haben Claude Code mit --plugin-dir oder --plugin-url gestartet, CLAUDE_CODE_PLUGIN_DIRS gesetzt, oder eine Agent SDK-App hat die plugins-Option übergeben. Es wird nur für diese Sitzung geladen Aktiviert für die Sitzung, es sei denn, das Manifest setzt defaultEnabled: false oder eine Einstellungsdatei setzt "<name>@inline": false
@skills-dir Sie haben ein Plugin-Verzeichnis mit einer .claude-plugin/plugin.json unter ~/.claude/skills/ oder dem .claude/skills/ des Projekts gespeichert Das Manifest's defaultEnabled, es sei denn, eine Einstellungsdatei setzt "<name>@skills-dir" auf true oder false
@synced Sie oder Ihre Organisation haben es für Ihr claude.ai-Konto aktiviert, und Claude Code hat es heruntergeladen Aktiviert, es sei denn, das Manifest setzt defaultEnabled: false oder eine Einstellungsdatei setzt "<name>@synced": false. Ein Plugin, das Ihre Organisation als erforderlich markiert, wird unabhängig geladen

Für ein Marktplatz-Plugin ist <name> der Eintragsname in marketplace.json; für @inline und @skills-dir ist es der name im Plugin-Manifest.

Die Ursprungsnamen in dieser Tabelle sind reserviert, daher kann kein Marktplatz inline, skills-dir oder synced genannt werden.

Eintragsname und Manifest-Name

Ein Marktplatz-Plugin hat zwei Namen, und sie können unterschiedlich sein:

  • Der Eintragsname in marketplace.json: der Installations- und Aktivierungsschlüssel. Es ist das, was Sie in enabledPlugins schreiben, worauf das Cache-Verzeichnis benannt ist, und was claude plugin list anzeigt
  • Der name im Manifest: worauf die Komponenten des Plugins namensraum sind, und was Namenskonflikte vergleichen

Plugins, die über ein Repository geteilt werden

Um ein Plugin über ein Repository zu teilen, listen Sie es unter enabledPlugins in .claude/settings.json auf oder platzieren Sie es unter .claude/skills/. Claude Code scannt das .claude/plugins/-Verzeichnis eines Projekts nicht.

Eine Cloud-Sitzung fügt die Marktplätze nicht hinzu, die ein Repository unter extraKnownMarketplaces auflistet, da dies den Workspace-Vertrauensdialog erfordert, den eine Cloud-Sitzung nie anzeigt.

Ein Plugin im Bereich Projekt-Fähigkeitsverzeichnis wird nur aus dem .claude/skills/ des primären Arbeitsverzeichnisses der Sitzung geladen und nur, nachdem Sie den Workspace-Vertrauensdialog für diesen Ordner akzeptiert haben. Es sucht nicht in übergeordneten Verzeichnissen bis zur Repository-Root wie einfache Fähigkeiten und Befehle. Wenn Sie von einem Unterverzeichnis aus starten, wird ein Plugin in der Repository-Root nicht geladen. Starten Sie stattdessen von der Repository-Root, oder verschieben Sie die Sitzung mit /cd auf v2.1.246 oder später dorthin.

Ein Plugin im Projekt-Bereich wird in das Repository eingecheckt und erreicht jeden Mitarbeiter, der es klont. Da dieser Inhalt aus dem Repository und nicht von Ihnen stammt, wird er nur nach der gleichen Vertrauensprüfung geladen, die für Projekt-Allow-Regeln in .claude/settings.json gilt. Ein übergeordnetes Verzeichnis zu vertrauen oder mit -p auszuführen ist nicht ausreichend. Komponenten, die Code ausführen, sind weiter eingeschränkt:

  • MCP-Server, die es deklariert, durchlaufen die gleiche Pro-Server-Genehmigung wie ein Projekt .mcp.json
  • MCP-Server, die es als MCP-Bundle deklariert, eine .mcpb- oder .dxt-Datei, oder aus einer Datei außerhalb des Plugin-Verzeichnisses werden übersprungen. Deklarieren Sie sie inline oder in einer .mcp.json im Plugin-Verzeichnis
  • Hintergrund-Monitore werden nicht geladen

Plugins im persönlichen Bereich haben keine dieser Einschränkungen.

Wie Sie --plugin-dir- und Fähigkeitsverzeichnis-Plugins schreiben, siehe Plugins erstellen.

Plugins, die von claude.ai synchronisiert werden

Ein Plugin, das Sie für Ihr claude.ai-Konto aktivieren, wird auch in Claude Code geladen, neben den Plugins, die Sie von Marktplätzen installieren. Dies umfasst Plugins, die Ihre Organisation für ihre Mitglieder aktiviert. Jedes dieser Plugins wird als <name>@synced geladen, ohne Marktplatz und ohne Installationsdatensatz.

In Terminal-Sitzungen werden die Fähigkeiten, Agenten, Hooks, MCP-Server und LSP-Server eines synchronisierten Plugins alle geladen, mit dem gleichen Vertrauen wie ein Marktplatz-Plugin, das Sie installiert haben.

Für die Komponenten, die Cowork lädt, siehe die Komponenten-Unterstützungstabelle auf claude.com.

Synchronisierte Plugins werden in Cowork-Sitzungen und in Terminal-Sitzungen geladen, in denen Sie sich mit Ihrem claude.ai-Konto anmelden:

  • Cowork: Claude Code lädt sie in die eigene Umgebung der Sitzung herunter, wenn die Sitzung startet
  • Terminal-Sitzungen: jedes Mal, wenn Sie Claude Code starten, wird es einmal im Hintergrund synchronisiert, neue und aktualisierte Plugins heruntergeladen und die Plugins entfernt, die Sie oder Ihre Organisation deaktiviert haben. Die Synchronisierung in Terminal-Sitzungen erfordert Claude Code v2.1.273 oder später

Synchronisierungszeitpunkt in Terminal-Sitzungen

Da die Terminal-Synchronisierung im Hintergrund läuft, kann sie nach dem Start Ihrer Sitzung abgeschlossen sein. Wenn sie ein synchronisiertes Plugin in einer interaktiven Sitzung hinzufügt, aktualisiert oder entfernt, sehen Sie Plugins changed. Run /reload-plugins to activate. Führen Sie /reload-plugins aus, um die Änderung in dieser Sitzung zu laden, oder lassen Sie sie für das nächste Mal, wenn Sie Claude Code starten.

Wenn Sie ein Plugin auf claude.ai aktivieren, während eine Sitzung läuft, wird das Plugin das nächste Mal heruntergeladen, wenn Sie Claude Code starten.

Anmeldeanforderungen für Terminal-Synchronisierung

In Ihrem Terminal werden Plugins nur in Sitzungen synchronisiert, in denen Sie sich mit Ihrem claude.ai-Konto anmelden.

Wenn Sie sich auf einer früheren Version von Claude Code angemeldet haben, deckt diese Anmeldung Plugins nicht ab, bis Claude Code sie im Hintergrund erneuert. Um schneller Zugriff zu erhalten, führen Sie /login erneut aus. Die Plugin-Synchronisierung startet dann das nächste Mal, wenn Sie Claude Code starten.

Steuern Sie, welche synchronisierten Plugins geladen werden

Sie können synchronisierte Plugins einzeln ausschalten, außer einem Plugin, das Ihre Organisation erfordert, oder alle synchronisierten Plugins auf dem Computer ausschalten:

  • Ein Plugin: claude plugin disable <name>@synced in Ihrer Shell und die /plugin Installed-Registerkarte in einer Sitzung speichern beide "<name>@synced": false in Ihrem Benutzer-Level enabledPlugins. Um das Plugin in einem Projekt in jeder Umgebung zu halten, setzen Sie den gleichen Schlüssel in der committed .claude/settings.json des Projekts
  • Jedes synchronisierte Plugin auf einem Computer: setzen Sie syncClaudeAiPlugins auf false in Ihren Benutzereinstellungen, oder Ihre Organisation setzt es in verwalteten Einstellungen. Claude Code stoppt das Herunterladen, und das nächste Mal, wenn Sie es starten, verschiebt es die Plugins, die es bereits synchronisiert hat, zu ~/.claude/plugins/.trash/ und lädt sie nicht mehr. Wenn Ihre Organisation Skills auf claude.ai ausschaltet, stoppt auch die Plugin-Synchronisierung
  • Ein Plugin, das Ihre Organisation erfordert: ein Plugin, das Ihre Organisation auf claude.ai als erforderlich markiert, wird geladen, auch wenn Sie es zuvor deaktiviert haben. claude plugin disable weigert sich mit Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it., und claude plugin list markiert es required by your org

Zum Entfernen eines Plugins auf claude.ai siehe Installierte Plugins verwalten.

Finden Sie heraus, wo ein Plugin aktiviert ist

Sie können einen enabledPlugins-Eintrag in einer von sechs Quellen setzen. Die Tabelle listet sie von niedrigster zu höchster Priorität auf und wer jede betrifft. Für die Einstellungsdateien selbst siehe Einstellungsdateien und wer sie beeinflussen.

Quelle Wo Sie es setzen Erreicht
--add-dir .claude/settings.json oder .claude/settings.local.json in einem Verzeichnis, das Sie mit --add-dir übergeben Nur diese Sitzung. Nur ein true-Wert hat eine Auswirkung, und jede andere Quelle überschreibt ihn
user ~/.claude/settings.json Sie, in jedem Projekt
project .claude/settings.json Jeder, der das Repository klont
local .claude/settings.local.json Sie, nur in diesem Repository
flag Der --settings-Wert, den Sie beim Start übergeben Nur diese Sitzung
managed Verwaltete Einstellungen Jeder Benutzer, den die Richtlinie abdeckt. true erzwingt Aktivierung und false blockiert, und keine andere Quelle überschreibt sie

Diese Quellen werden Schlüssel für Schlüssel zusammengeführt. Für jede Plugin-ID ist der Wert, der gilt, der aus der höchsten Prioritätsquelle, die die ID erwähnt. Eine Quelle, die die ID nicht erwähnt, lässt den Wert aus der niedrigeren Prioritätsquelle in Kraft.

In Benutzereinstellungen deaktiviert, wird aber immer noch geladen

Wenn Sie ein Plugin in ~/.claude/settings.json auf false setzen und es wird immer noch geladen, überschreibt ein true in einer höheren Prioritätsquelle es. Die Zeile des Plugins in claude plugin list und in /plugin zeigt Disabled in ~/.claude/settings.json but still loads — project settings enable it, which overrides your user setting. Die Nachricht nennt die Quelle, die Sie überschrieben hat: project, project, gitignored für .claude/settings.local.json, cli flag, oder managed.

Um sich von einem Projekt-aktivierten Plugin auf Ihrem Computer abzumelden, setzen Sie die ID auf false in .claude/settings.local.json, die höhere Priorität als die Projektdatei hat.

In Projekteinstellungen aktiviert, aber nicht installiert

Wenn das einzige true eines Plugins in der .claude/settings.json des Projekts ist, ruft Claude Code es nicht auf einem Computer ab, auf dem es nicht installiert ist, es sei denn, sein Marktplatz-Eintrag hat eine relative-Pfad-Quelle oder ein Seed-Verzeichnis hält es bereits. Stattdessen zeigt die /plugin Errors-Registerkarte Plugin "<name>" is enabled in project settings but isn't installed here.

Ein Relative-Pfad-Plugin benötigt keinen Installationsdatensatz, da es vom Marktplatz selbst geladen wird.

Claude Code ruft ein Plugin mit einer externen Quelle nur ab, wenn eine dieser Quellen es auf true setzt:

  • Ihre Benutzereinstellungen
  • Eine .claude/settings.local.json, die git nicht verfolgt
  • Das --settings-Flag
  • Verwaltete Einstellungen

Finden Sie Plugins auf der Festplatte

Claude Code behält Plugin-Dateien und Zustandsdatensätze unter einer Plugin-Root, die ~/.claude/plugins ist, es sei denn, Sie setzen CLAUDE_CODE_PLUGIN_CACHE_DIR. Jeder Pfad in der Tabelle ist relativ zu dieser Root.

Pfad Was er enthält
cache/<marketplace>/<plugin>/<version>/ Ein Verzeichnis pro installierte Version eines Marktplatz-Plugins. <plugin> ist der Marktplatz-Eintragsname und <version> ist die aufgelöste Version. ${CLAUDE_PLUGIN_ROOT} zeigt auf dieses Verzeichnis
data/<plugin-id>/ Das persistente Verzeichnis des Plugins, das als ${CLAUDE_PLUGIN_DATA} verfügbar gemacht wird. Wie <plugin-id> gebildet wird, siehe Pfadvariablen und persistente Daten. Claude Code erstellt es, wenn eine Plugin-Komponente es zuerst verwendet, und behält es über Updates hinweg. Standardmäßig löscht Claude Code es, wenn Sie das Plugin aus seinem letzten Bereich deinstallieren. Für --keep-data und die anderen Fälle, in denen es erhalten bleibt, siehe Plugin deinstallieren
marketplaces/<name>/ Der Klon oder Download eines Marktplatzes, der von GitHub, einem anderen Git-Host oder einer URL hinzugefügt wurde. Ein Marktplatz, der von einer lokalen file- oder directory-Quelle hinzugefügt wurde, hat hier keine Kopie, und seine installLocation in known_marketplaces.json ist der Pfad, den Sie angegeben haben
synced/ Die Plugins, die Claude Code von Ihrem claude.ai-Konto synchronisiert hat
.trash/ Plugins, die die claude.ai-Synchronisierung entfernt hat, z. B. nachdem Sie eines auf claude.ai ausgeschaltet haben oder die Synchronisierung gestoppt haben
installed_plugins.json und known_marketplaces.json Die Datensätze darüber, was Claude Code installiert hat und welche Marktplätze es abgerufen hat, beschrieben unter Überprüfen Sie, welche Phase ein Plugin erreicht hat. Ein auf claude.ai gehosteter Marktplatz wird stattdessen in known_marketplaces_claudeai.json aufgezeichnet
flagged-plugins.json Plugins, die Claude Code deinstalliert hat, weil ihr Marktplatz sie delisted hat. Sie erscheinen im Flagged-Bereich von /plugin; siehe Einen Marktplatz hosten

Da ${CLAUDE_PLUGIN_ROOT} auf ein Versionsverzeichnis zeigt, ändert sich der Root-Pfad eines Plugins mit jeder Version. Behalten Sie die dauerhaften Dateien eines Plugins stattdessen in ${CLAUDE_PLUGIN_DATA}.

In-Place- und kopierte Plugins

Claude Code lädt einige Plugins an Ort und Stelle von dort, wo Sie sie aufbewahren, und kopiert den Rest in den Cache, je nach ihrem Ursprung:

  • --plugin-dir- und Fähigkeitsverzeichnis-Plugins: das Verzeichnis wird an Ort und Stelle geladen und wird nie kopiert. Ein --plugin-url-Archiv oder eine --plugin-dir .zip wird zuerst in ein Sitzungs-Temp-Verzeichnis extrahiert
  • Relative-Pfad-Plugins in einem Marktplatz, den Sie von einem lokalen Verzeichnis hinzugefügt haben: das Plugin wird an Ort und Stelle von seinem Pfad im Marktplatz-Ordner geladen. Ihre Änderungen am Quellverzeichnis treten beim nächsten Sitzungsstart oder /reload-plugins in Kraft, und Sie müssen die Version nicht erhöhen. Die Hook-Prozesse des Plugins und MCP- und LSP-Server erhalten ein CLAUDE_PLUGIN_ROOT, das auf das Quellverzeichnis zeigt. Für seine Node.js-Paketabhängigkeiten siehe Wenn die Abhängigkeitsinstallation läuft
  • command-Quellen-Plugins im Link-Modus: das Verzeichnis, das der Befehl gedruckt hat, wird an Ort und Stelle geladen, durch Links im Cache-Eintrag
  • Jedes andere Marktplatz-Plugin: Claude Code kopiert das Plugin beim Installieren in cache/<marketplace>/<plugin>/<version>/ und lädt diese Kopie. Dateien außerhalb des Plugin-Verzeichnisses werden nicht kopiert, daher findet ein Skript in einem kopierten Plugin, das einen Pfad über der Plugin-Root liest, wie ../shared, sie nicht

Pfade, die dem Plugin-Verzeichnis entkommen

Ob ein Plugin an Ort und Stelle oder aus einer zwischengespeicherten Kopie geladen wird, Claude Code lässt es nicht zu, Komponenten außerhalb seines eigenen Verzeichnisses zu deklarieren. Es lehnt einen Komponentenpfad ab, der außerhalb der Plugin-Root aufgelöst wird, ob der Pfad in plugin.json oder in einem Marktplatz-Eintrag deklariert ist:

  • Ein Pfad, der außerhalb des Plugins zeigt, wie geschrieben, wie ../shared-utils
  • Ein Symlink, der außerhalb des Plugins führt, außer Links zwischen Plugins innerhalb eines Marktplatzes
  • Auf macOS und Linux, ein Pfad, der irgendwo einen Backslash enthält, auch wenn der Pfad im Plugin bleibt. Komponenten, die mit Backslash-Pfaden deklariert werden, werden daher nur unter Windows geladen, daher schreiben Sie Komponentenpfade mit Schrägstrichen, wie ./commands/deploy.md

Ein abgelehnter Pfad erscheint als path escapes plugin directory-Fehler, und das Plugin wird ohne diese Komponente geladen.

Bereinigung vorheriger Versionen

Wenn Sie ein Plugin aktualisieren oder deinstallieren, schreibt Claude Code einen .orphaned_at-Marker in das vorherige Versionsverzeichnis. Es entfernt dieses Verzeichnis 14 Tage später in einer Hintergrund-Bereinigung, daher läuft eine Sitzung, die die alte Version bereits geladen hat, weiter.

Der Sweep läuft nur, während installed_plugins.json mindestens eine Installation aufzeichnet. Nachdem Sie Ihr letztes Plugin deinstalliert haben, bleiben verwaiste Verzeichnisse, bis Sie ein anderes installieren.

Node.js-Paketabhängigkeiten

Wenn Claude Code ein Plugin in den Cache kopiert, installiert es auch die Node.js-Paketabhängigkeiten des Plugins dort, damit die Hooks und MCP-Server des Plugins sie laden können.

Dieser Abschnitt behandelt die npm- und Bun-Pakete, die ein Plugin in seiner eigenen package.json deklariert. Für Plugins, die von anderen Plugins abhängen, siehe Plugin-Abhängigkeitsversionen.

Wenn die Abhängigkeitsinstallation läuft

Claude Code führt die Installation im kopierten Versionsverzeichnis jedes Mal aus, wenn es eines erstellt:

  • Wenn Sie ein Plugin installieren
  • Wenn Claude Code ein Plugin auf eine neue Version aktualisiert
  • Beim Sitzungsstart, wenn ein aktiviertes Plugin noch nicht zwischengespeichert ist, z. B. auf einem neuen Computer

Für ein Relative-Pfad-Plugin, das an Ort und Stelle geladen wird von einem lokalen Verzeichnis-Marktplatz, installiert Claude Code die Abhängigkeiten nicht in das Quellverzeichnis. Installieren Sie sie dort selbst, oder von einem Hook in ${CLAUDE_PLUGIN_DATA}.

Die Installation läuft nur, wenn das Plugin-Root-Verzeichnis sowohl eine package.json als auch eine unterstützte Lockdatei enthält. Die Lockdatei entscheidet, welchen Befehl Claude Code ausführt:

Lockdatei Befehl
bun.lock oder bun.lockb bun install --frozen-lockfile --ignore-scripts
npm-shrinkwrap.json oder package-lock.json npm ci --ignore-scripts

Wenn ein Plugin mehr als eine dieser Lockdateien enthält, verwendet Claude Code die erste Übereinstimmung, Überprüfung in Reihenfolge: bun.lock, bun.lockb, npm-shrinkwrap.json, package-lock.json.

Claude Code überspringt die Installation für Yarn- und pnpm-Lockdateien und für eine bunfig.toml neben der Bun-Lockdatei:

  • Wenn Ihr Plugin nur eine yarn.lock oder pnpm-lock.yaml hat, ersetzen Sie sie durch eine npm-Lockdatei
  • Wenn eine bunfig.toml im gleichen Verzeichnis wie die Bun-Lockdatei ist, entfernen Sie die bunfig.toml, oder ersetzen Sie die Bun-Lockdatei durch eine npm-Lockdatei

Fügen Sie eine npm-Lockdatei ein, um die meisten Benutzer zu erreichen. Claude Code führt den Paketmanager der übereinstimmenden Lockdatei aus dem PATH des Benutzers aus und versucht nicht den anderen Lockdatei-Paketmanager, wenn dieser fehlt.

Für ein Plugin, das über eine npm-Quelle verteilt wird, verwenden Sie npm-shrinkwrap.json, da npm package-lock.json aus veröffentlichten Paketen ausschließt.

Grenzen der Abhängigkeitsinstallation

Claude Code beschränkt diese Abhängigkeitsinstallation so, dass kein Code aus dem Plugin oder seinen Paketen während der Installation ausgeführt wird, und begrenzt, wie lange sie laufen kann:

  • Gefrorene Auflösung: Bun und npm installieren genau das, was die Lockdatei anheftet, und schlagen fehl, anstatt Versionen erneut aufzulösen, wenn package.json und die Lockdatei nicht übereinstimmen
  • Keine Lifecycle-Skripte: --ignore-scripts hält preinstall-, install- und postinstall-Skripte davon ab, zu laufen, daher laden Abhängigkeiten, die native Module in diesen Skripten erstellen, herunter, werden aber während dieser Installation nicht kompiliert
  • 60-Sekunden-Timeout: Claude Code stoppt eine Installation, die länger läuft, und behandelt sie als fehlgeschlagen

Claude Code ruft ein npm-Quellen-Plugin vor dieser Abhängigkeitsinstallation ab, und keines der Installationsskripte des Pakets selbst läuft während des Abrufs. Siehe npm-Plugin-Quelle.

Sie können die automatische Installation nicht ausschalten. Keine Einstellung oder Umgebungsvariable deaktiviert sie.

In eingeschränkten Netzwerken siehe die Netzwerkzugriffsanforderungen für die Hosts, die Sie zulassen müssen.

Wenn die Abhängigkeitsinstallation fehlschlägt oder übersprungen wird

Eine fehlgeschlagene oder übersprungene Installation blockiert das Plugin nie, und jeder Fall hinterlässt ein anderes Zeichen:

  • Eine fehlgeschlagene Installation oder eine, die übersprungen wird, weil eine Yarn- oder pnpm-Lockdatei oder eine bunfig.toml vorhanden ist, erscheint als Warnung in der claude --debug-Ausgabe
  • Ein Plugin mit einer package.json und keiner Lockdatei wird ohne Logeintrag übersprungen
  • Eine Timeout-Installation kann einen teilweisen node_modules-Baum in der zwischengespeicherten Kopie hinterlassen

Wenn die automatische Installation eine Abhängigkeit nicht bereitstellen kann, installieren Sie sie von einem Hook in das persistente Datenverzeichnis. Dies umfasst Pakete, die ihre Lifecycle-Skripte zum Erstellen benötigen, Python-Abhängigkeiten und Plugins, die mit Yarn oder pnpm gesperrt sind.

Versionen und Updates

Wenn der Autor eines Plugins neue Commits gepusht hat und claude plugin update gibt <name> is already at the latest version (<version>). aus, bleibt die Version, die Claude Code für das Plugin berechnet, unverändert, sodass sich nichts auf der Festplatte ändert.

Claude Code berechnet eine Version für jedes Plugin, das es installiert, und diese Version ist die Art und Weise, wie es ein Update erkennt. claude plugin update und die automatische Hintergrund-Aktualisierung berechnen die Version erneut und überspringen das Plugin, wenn sie mit dem übereinstimmt, was installed_plugins.json aufzeichnet.

Die Version benennt auch das Cache-Verzeichnis des Plugins.

Ein Manifest, das "version" festlegt, ist eine Möglichkeit, wie die berechnete Version über Commits hinweg gleich bleibt. Siehe How Claude Code computes the version für die Auflösungsreihenfolge.

Ein Plugin, das in place aus einem lokalen Marketplace-Verzeichnis geladen wird, lädt seine aktuellen Quelldateien bei jedem Sitzungsstart, unabhängig davon, was seine Versionsnummer sagt. Für ein Plugin aus einem Marketplace, der auf claude.ai gehostet wird, ist die Version, die claude.ai für das Plugin aufzeichnet, seine Version, und das Manifest's version wird nicht gelesen.

How Claude Code computes the version

Für einen Marketplace, den Sie nach Quelle hinzugefügt haben, wählt Claude Code die Regel nach dem source-Typ des Plugin-Marketplace-Eintrags. Die Marketplace-Referenz listet die Quellentypen auf. Für jeden Quellentyp in dieser Liste außer command:

  1. Das version-Feld im Manifest des Plugins kommt zuerst
  2. Dann das version-Feld im Plugin-Marketplace-Eintrag
  3. Wenn keines gesetzt ist, kommt die Version vom Quellentyp:
Quellentyp Version, wenn kein version-Feld gesetzt ist
github, url oder git-subdir Der Commit-SHA der Quelle, gekürzt auf 12 Zeichen. Eine git-subdir-Version trägt auch einen Hash des Unterverzeichnispfads
archive Der SHA-256-Digest, gekürzt auf 12 Zeichen: der sha256-Pin im Marketplace-Eintrag oder der Digest der heruntergeladenen Datei, wenn kein Pin vorhanden ist
Relativer Pfad in einem Git-gehosteten Marketplace Der Commit-SHA des installierten Verzeichnisses
Lokales Verzeichnis, wenn weder das Plugin-Verzeichnis noch sein Marketplace ein Git-Repository ist unknown
npm unknown

Claude Code nimmt die Version nicht aus einem Repository, das den Installationspfad umschließt, wie z. B. ein Git-verwaltetes ~/.claude.

Für eine command-Quelle leitet Claude Code die Version immer von dem ab, was der Befehl produziert hat: ein 12-Zeichen-Hash allein oder <manifest version>-<hash>, wenn das Manifest einen setzt. Der version-Eintrag des Marketplace wird für Befehlsquellen ignoriert. Für das, was der Hash abdeckt, siehe Copy mode and link mode.

Da das Manifest zuerst kommt, behält ein Manifest, das "version": "1.0.0" festlegt, jeden Benutzer auf der zwischengespeicherten Kopie, bis sein Autor die Zeichenkette ändert, egal wie viele Commits er pusht. Um Benutzern zu ermöglichen, stattdessen Commits zu verfolgen, lassen Sie version sowohl im Manifest als auch im Eintrag weg. Host a marketplace behandelt, welche Wahl zu welchem Release-Setup passt.

When Claude Code refreshes a marketplace before an install

Wenn Sie ein Plugin installieren, sucht Claude Code es in seiner lokalen Kopie des Marketplace-Katalogs auf. Sie können /plugin install in einer Sitzung oder claude plugin install in Ihrer Shell ausführen und das Plugin mit oder ohne seinen Marketplace benennen. Die Tabelle zeigt, welche dieser Kombinationen die lokale Kopie aktualisieren.

Plugin-Name Befehl Was Claude Code aktualisiert
name@marketplace /plugin install oder claude plugin install Der benannte Marketplace, vor der Suche
name allein /plugin install Nur Marketplaces, die Auto-Update aktiviert haben, und nur nach der Suche fehlschlägt
name allein claude plugin install Nichts. Es liest die zwischengespeicherten Kataloge ohne Aktualisierung

Die Aktualisierung vor einer name@marketplace-Installation hängt nicht von der Auto-Update-Einstellung des Marketplace oder von DISABLE_AUTOUPDATER ab.

Wenn die Aktualisierung fehlschlägt, wird die Installation aus dem zwischengespeicherten Katalog fortgesetzt und claude plugin install meldet marketplace not refreshed.

Claude Code überspringt die Aktualisierung vor einer name@marketplace-Installation, wenn:

  • Der Marketplace wurde aus einer lokalen file- oder directory-Quelle hinzugefügt oder ist inline in Einstellungen mit einer settings-Quelle definiert
  • Ein Seed-Verzeichnis stellt den Marketplace bereit
  • Claude Code hat den Marketplace in den letzten 30 Sekunden aktualisiert
  • Sie setzen CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
  • Verwaltete Einstellungen blockieren den Marketplace, in welchem Fall Claude Code auch die Installation verweigert

When auto-update runs

In einer interaktiven Sitzung wartet Claude Code nach dem Senden Ihrer ersten Nachricht eine zufällige Verzögerung von bis zu zehn Minuten. Anschließend aktualisiert es jeden Marketplace mit aktiviertem Auto-Update und aktualisiert die von ihnen installierten Plugins auf der Festplatte.

Die laufende Sitzung behält die Versionen, die sie geladen hat, und Sie sehen Plugin updated: <name> · Run /reload-plugins to apply. Unabhängig davon, ob Sie neu laden oder nicht, werden die neuen Versionen beim nächsten Start geladen.

Which marketplaces and plugins auto-update

Ob ein Marketplace automatisch aktualisiert wird, folgt dem ersten dieser Punkte, der gesetzt ist:

  1. autoUpdate auf seinem extraKnownMarketplaces-Eintrag in einer Einstellungsdatei
  2. autoUpdate auf seinem known_marketplaces.json-Eintrag, den der Enable auto-update-Schalter unter /plugin Marketplaces schreibt. Wenn eine Einstellungsdatei den Marketplace auch unter extraKnownMarketplaces deklariert, schreibt der Schalter autoUpdate auch in diesen Einstellungseintrag
  3. Der Standard: an für Anthropics offizielle Marketplaces wie claude-plugins-official, aus für knowledge-work-plugins und first-party-plugins, an für Marketplaces, die von claude.ai hinzugefügt wurden, und aus für jeden anderen Marketplace

Wenn Sie DISABLE_UPDATES=1, DISABLE_AUTOUPDATER=1 oder CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 setzen, ist der gesamte Durchgang aus und der Enable auto-update-Schalter ist verborgen, es sei denn, Sie setzen auch FORCE_AUTOUPDATE_PLUGINS=1. Die Umgebungsvariablen-Referenz behandelt die breitere Auswirkung jeder Variablen.

Auto-Update überspringt auch ein Plugin, dessen Marketplace-Eintrag einen headersHelper deklariert. Installs and updates that refuse a command instead of asking erklärt, wann ein solches Plugin in der /plugin Errors-Registerkarte angezeigt wird und wie Sie es von dort aus aktualisieren.

Wenn ein kopiertes Plugin während einer Sitzung aktualisiert wird, verwenden Hook-Befehle, Monitore, MCP-Server und LSP-Server weiterhin den Pfad der vorherigen Version. Führen Sie /reload-plugins aus, um Hooks, MCP-Server und LSP-Server zum neuen Pfad zu wechseln. Monitore erfordern einen Sitzungsneustart.

When a command source re-runs

Plugins mit einer command-Quelle warten nicht auf den Auto-Update-Durchgang. Das gedruckte Verzeichnis spiegelt den Zustand des Tools zum Zeitpunkt der Befehlsausführung wider, daher führt Claude Code den Befehl aus, den Sie akzeptiert haben zu diesen Zeiten erneut aus:

  • Jedes Mal, wenn Sie das Plugin installieren oder aktualisieren
  • Einmal pro Sitzung für jedes aktivierte befehlsgesteuerte Plugin im Hintergrund, kurz nach dem Sitzungsstart. Dieser Durchgang hängt nicht von der Auto-Update-Einstellung des Marketplace oder von DISABLE_AUTOUPDATER ab
  • Beim Start oder auf /reload-plugins, wenn die installierte Version eines aktivierten Plugins im Plugin-Cache fehlt

Claude Code überspringt die beiden Hintergrund-Durchgänge, wenn Sie CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC setzen. Explizite Installationen und Updates führen den Befehl mit dieser Variablen gesetzt immer noch aus.

Wenn sich die gehashte Ausgabe des Befehls geändert hat, installiert Claude Code das Ergebnis als neue Version und lädt es in der laufenden interaktiven Sitzung neu, wobei die gleichen Komponenten gewechselt werden, die /reload-plugins wechselt. Sie sehen eine Benachrichtigung, dass das Plugin neu geladen wurde.

Wenn das Neuladen an Ort und Stelle den Prompt-Cache der Sitzung ungültig machen würde, fordert Claude Code Sie stattdessen auf, /reload-plugins auszuführen, das vor den Cache-Kosten warnt und angewendet wird, wenn es mit --force erneut ausgeführt wird.

Namenskonflikte

Wenn aktivierte Plugins aus verschiedenen Ursprüngen einen Manifest-Namen teilen, entscheidet diese Reihenfolge, welche geladen wird, von höchster zu niedrigster Priorität:

  1. Ein Plugin, dessen ID in verwalteten Einstellungen enabledPlugins erscheint, als true oder false. Eine --plugin-dir-Kopie, deren Manifest-Name dem Namen-Teil der ID entspricht, wird nicht geladen, und Sie sehen --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings
  2. Ein aktiviertes --plugin-dir-, --plugin-url- oder CLAUDE_CODE_PLUGIN_DIRS-Plugin. Es ersetzt ein gleichnamiges installiertes Marktplatz-Plugin oder Fähigkeitsverzeichnis-Plugin:
    • Ein installiertes Marktplatz-Plugin: stillschweigend ersetzt. claude plugin list zeigt die Marktplatz-Zeile immer noch als aktiviert, da diese Zeile Ihre Einstellungen widerspiegelt. Nur das Protokoll, das Claude Code unter ~/.claude/debug/ schreibt, wenn Sie mit --debug starten, zeichnet Plugin "<name>" from --plugin-dir overrides installed version auf
    • Ein Fähigkeitsverzeichnis-Plugin: ersetzt mit einer /plugin Errors-Registerkarte-Zeile, die Not loaded — the name "<name>" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence liest
  3. Ein installiertes Marktplatz-Plugin. Ein Fähigkeitsverzeichnis-Plugin mit dem gleichen Namen erhält die gleiche Not loaded-Zeile, benennend das installierte Plugin
  4. Ein Fähigkeitsverzeichnis-Plugin. Zwischen zwei davon wird die Kopie unter ~/.claude/skills/ geladen und die Kopie des Projekts .claude/skills/ wird gelöscht, mit einer Zeile, die sagt, welcher Pfad sie überschattet hat
  5. Ein Plugin, das von claude.ai synchronisiert wird. Wenn ein aktiviertes Plugin aus einem anderen Ursprung seinen Namen entspricht, lädt Claude Code dieses Plugin und meldet die synchronisierte Kopie als nicht geladen. Um stattdessen die claude.ai-Kopie zu verwenden, deaktivieren Sie Ihre eigene Kopie

Da die Reihenfolge Manifest-Namen vergleicht, ersetzt ein --plugin-dir-Plugin namens hello-plugin hello@example-marketplace, wenn das Plugin-Manifest auch "name": "hello-plugin" sagt.

Halten Sie ein Sitzungs-Only-Plugin davon ab, zu laden

Um zu verhindern, dass ein --plugin-dir-Plugin etwas überschattet, oder um eines auszuschalten, wenn ein übergeordneter Prozess das Flag für Sie übergibt, setzen Sie seine ID auf false in einer beliebigen Einstellungsdatei. Für ein Plugin, dessen Manifest-Name hello-plugin ist, ist der Eintrag "enabledPlugins": {"hello-plugin@inline": false}. Ein deaktiviertes Sitzungs-Only-Plugin überschattet nicht, daher wird die Marktplatz- oder Fähigkeitsverzeichnis-Kopie stattdessen geladen.

Nächste Schritte