Symptom → schnellster Weg zur Ursache: Claude Code Hooks lösen auf dem Remote-Mac nicht aus? Prüfen Sie zuerst die tatsächlich geladene Einstellungsdatei sowie Ereignis und Matcher. Untersuchen Sie danach Konto, Skriptumgebung und Rückgabe; installieren Sie Claude Code nicht vorschnell neu.

Dieser Leitfaden ist für Entwickler gedacht, die nach einer Änderung weder Formatierung noch Prüfungen oder Befehlsblockaden sehen.
Er richtet sich außerdem an DevOps-Teams, die Hook-Ergebnisse vor einem Xcode-Build bewerten müssen.
Plattformverantwortliche finden hier eine Trennung zwischen persönlichen, projektbezogenen und zentral verwalteten Einstellungen.

1. Fehlerbild eingrenzen, bevor Sie Einstellungen ändern

Ein Hook kann an unterschiedlichen Stellen scheitern. „Nichts passiert“ beschreibt noch keine Ursache. Trennen Sie zunächst diese Fälle:

  • Das erwartete Ereignis entsteht nicht.
  • Das Ereignis entsteht, aber der Matcher passt nicht.
  • Der Hook wird ausgewählt, doch das Skript startet nicht.
  • Das Skript läuft, aber sein Ergebnis bewirkt keine sichtbare Entscheidung.

Diese Trennung verhindert, dass Sie etwa Dateirechte ändern, obwohl Claude Code das konfigurierte Ereignis gar nicht erreicht. Sie verhindert auch eine Neuinstallation, die eine falsche Konfigurationsquelle oder ein anderes Konto nicht korrigieren würde.

Wählen Sie eine möglichst kleine, sichere Aktion, die den Fehler reproduziert. Wenn Sie beispielsweise eine Prüfung vor einem Tool-Aufruf erwarten, lösen Sie genau diesen Tool-Aufruf einmal aus. Ändern Sie dabei weder mehrere Matcher-Bedingungen noch mehrere Hook-Ereignisse zugleich. Notieren Sie, welche Aktion Sie ausgeführt haben und welches Ergebnis Sie erwartet haben.

Aktivieren Sie anschließend die von Claude Code dokumentierte Hook-Diagnose und beobachten Sie den Sitzungsverlauf. Die offizielle Dokumentation zur Hook-Fehlersuche und Protokollierung beschreibt, welche Informationen Sie zur Ausführung heranziehen können. Protokolle sollten den Ablauf belegen, nicht vertrauliche Werte enthalten: Entfernen Sie Tokens, Zugangsdaten und private Inhalte aus Diagnoseausgaben.

Ein praktischer Fall: In einer interaktiven SSH-Sitzung sehen Sie eine Formatierung, im Runner-Prozess jedoch nicht. Das ist noch kein Beleg für einen Fehler im Formatter. Zuerst müssen Sie feststellen, ob beide Abläufe dieselbe Einstellung laden, dasselbe Ereignis auslösen und unter demselben Konto laufen. Erst danach ist ein Vergleich der Skriptausgabe sinnvoll.

2. Einstellungsquelle und ausführendes Konto abgleichen

Auf einem Remote-Mac können interaktive SSH-Sitzung, Dienstprozess und CI-Aufruf mit unterschiedlichen Konten oder Arbeitsverzeichnissen starten. Dadurch kann Claude Code eine andere Konfiguration finden als erwartet. Gleichen Sie daher nicht nur Dateien ab, sondern den gesamten Startkontext.

Die Dokumentation zu Claude Code-Einstellungsdateien und ihren Geltungsbereichen unterscheidet zwischen projektbezogenen, benutzerspezifischen, lokalen und verwalteten Einstellungen. Prüfen Sie, welche Quelle für Ihre Sitzung gilt. Eine lokale Benutzerdatei ist nicht automatisch für ein anderes Betriebssystemkonto vorhanden. Ebenso sollten Sie verwaltete Richtlinien nicht mit einer projektbezogenen Einstellung gleichsetzen.

Ermitteln Sie für jede betroffene Ausführungsart:

  • Welches Konto startet Claude Code?
  • In welchem Verzeichnis beginnt der Prozess?
  • Welche Konfigurationsdateien sind für dieses Konto und Projekt erreichbar?
  • Gibt es eine lokale Einstellung, die nur auf diesem Rechner oder in diesem Arbeitsverzeichnis gilt?
  • Greift eine zentral verwaltete Vorgabe, die lokale Änderungen beeinflusst?

Vergleichen Sie die Antworten für die interaktive SSH-Sitzung und den CI- oder Runner-Dienst. Prüfen Sie Dateipfade und Besitzverhältnisse, ohne Konfigurationsinhalte mit Geheimnissen in ein öffentliches Protokoll zu kopieren. Ein reduzierter, nicht vertraulicher Nachweis genügt: Konto, Arbeitsverzeichnis und verwendete Konfigurationsquelle.

Ändern Sie nicht mehrere Einstellungsdateien gleichzeitig. Sichern Sie den Ausgangszustand und ändern Sie gezielt nur die Quelle, die im fehlerhaften Startkontext tatsächlich geladen wird.

Bewerten Sie auch den Kompromiss der jeweiligen Ablage. Eine Projekteinstellung erleichtert eine nachvollziehbare Zusammenarbeit, muss aber zum Projekt passen und sicher geprüft werden. Eine benutzerspezifische Einstellung eignet sich für persönliche Werkzeuge, ist auf einem gemeinsam genutzten Host aber nicht automatisch für weitere Konten wirksam. Eine verwaltete Vorgabe kann gemeinsame Regeln durchsetzen; Änderungen daran gehören in den vorgesehenen Verwaltungsprozess und nicht in einen spontanen lokalen Workaround.

Wenn die erwartete Datei nicht geladen wird, dokumentieren Sie den Grund und korrigieren Sie zuerst Konto, Arbeitsverzeichnis oder Ablage. Wiederholen Sie denselben Minimaltest. Bleibt die Einstellung sichtbar, aber das Ereignis aus, gehen Sie zur Ereignis- und Matcher-Prüfung über.

3. Ereignis und Matcher gezielt gegen den tatsächlichen Aufruf prüfen

Ein häufiger Denkfehler ist, verschiedene Momente einer Sitzung als austauschbar zu behandeln. Ein Hook vor einem Tool-Aufruf, ein Hook nach einem Aufruf und ein Hook am Sitzungsende beobachten unterschiedliche Situationen. Ein Abschlussereignis ersetzt daher keine Prüfung vor dem Werkzeugaufruf. Welches Ereignis greift, muss zu der Aktion passen, die Sie kontrollieren wollen; die verfügbaren Ereignisse und ihre Bedeutung sind in der offiziellen Hooks-Dokumentation beschrieben.

Prüfen Sie danach den Matcher. Entscheidend ist nicht, welcher Werkzeugname Ihnen logisch erscheint, sondern welcher Name und welche Felder im betreffenden Ereignis tatsächlich zur Verfügung stehen. Ein Matcher kann syntaktisch vorhanden sein und dennoch nie passen, wenn er einen anderen Werkzeugnamen oder eine andere Bedingung erwartet.

Gehen Sie in dieser Reihenfolge vor:

  1. Formulieren Sie die konkrete Aktion, die den Hook auslösen soll.
  2. Ordnen Sie ihr das passende Ereignis zu.
  3. Prüfen Sie den dokumentierten Werkzeugnamen und die verfügbaren Matcher-Felder.
  4. Testen Sie zunächst mit einer einfachen Bedingung.
  5. Ergänzen Sie Filter einzeln und prüfen Sie nach jeder Änderung erneut.

Wenn die Diagnose das Ereignis zeigt, aber keinen passenden Hook, liegt der Verdacht bei der Zuordnung oder Filterbedingung. Fehlt bereits das Ereignis, prüfen Sie, ob Ihre Aktion den betreffenden Ablauf überhaupt erzeugt und ob die erwartete Einstellung geladen ist. Diese Unterscheidung spart Zeit gegenüber dem gleichzeitigen Umbau von Ereignis, Matcher und Skript.

Nehmen Sie außerdem keine stillschweigende Sicherheitswirkung an. Ein Hook kann eine passende Aktion steuern, aber die Berechtigungsregeln bleiben eine separate Kontrollebene. Die Dokumentation zu Claude Code-Berechtigungen erläutert diese Konfiguration. Behandeln Sie einen Hook daher nicht als Ersatz für Berechtigungen, Betriebssystemzugriff oder eine menschliche Freigabe, wenn diese erforderlich ist.

4. Remote-Skriptumgebung mit dem Startkontext vergleichen

Passt Ereignis und Matcher, aber das Skript läuft nicht wie erwartet, vergleichen Sie die Prozessumgebung. Eine interaktive Shell kann Variablen aus Startdateien laden, die einem nicht interaktiven Dienst fehlen. Ein Befehl, der in Ihrer SSH-Sitzung verfügbar ist, muss deshalb nicht im Runner-Kontext auflösbar sein.

Prüfen Sie in dem betroffenen Konto und Startmodus:

  • Ist die Skriptdatei ausführbar und für dieses Konto lesbar?
  • Existiert der angegebene Interpreter an genau diesem Pfad?
  • Enthält PATH die benötigten Programme?
  • Stimmen Arbeitsverzeichnis und relative Pfade?
  • Darf das Konto auf benötigte Dateien zugreifen und Ergebnisse schreiben?
  • Sind Abhängigkeiten in diesem Kontext installiert und aufrufbar?

Bei „Befehl nicht gefunden“ erfassen Sie PATH und den tatsächlichen Interpreter im Hook-Prozess, statt die Ausgabe einer interaktiven Shell als Beleg zu verwenden. Verwenden Sie, wo sinnvoll, einen expliziten Interpreterpfad und definieren Sie notwendige Umgebungsvariablen im vorgesehenen Startkontext. Vermeiden Sie es, sich auf Shell-Aliase oder ausschließlich interaktive Initialisierungsdateien zu verlassen.

Für die Diagnose genügt eine harmlose Ausgabe mit Prozesskonto, Arbeitsverzeichnis und den relevanten Pfaden. Protokollieren Sie weder Geheimnisse noch vollständige Umgebungsvariablen, wenn darin Zugangsdaten enthalten sein könnten. Prüfen Sie außerdem, ob ein Schreibfehler tatsächlich vom Hook stammt oder erst in einem späteren CI-Schritt auftritt.

Ein nützlicher Vergleich ist eine kleine Tabelle in Ihrem eigenen Fehlerprotokoll: SSH-Sitzung und Runner-Konto jeweils mit Konto, Arbeitsverzeichnis, Interpreter, relevantem PATH-Eintrag und Ergebnis. So wird sichtbar, ob der Unterschied bei der Shell-Initialisierung, der Berechtigung oder bei einer fehlenden Abhängigkeit liegt. Legen Sie keine erwarteten Werte fest, bevor Sie den realen Prozesszustand ermittelt haben.

5. Rückgabe und Wirkung auseinanderhalten

Ein gestartetes Skript ist noch kein wirksamer Hook. Prüfen Sie, was der Handler einliest, was er ausgibt und welchen Status er zurückliefert. Die erwarteten Eingabe- und Ausgabeformen sowie die Bedeutung der Rückgabe hängen vom jeweiligen Ereignis und der dokumentierten Hook-Schnittstelle ab. Nutzen Sie dafür die offizielle Referenz zu Hook-Ereignissen und Rückgaben, statt ein JSON-Format oder einen Exitstatus zu erraten.

Testen Sie zwei Fälle getrennt: einen Durchlauf ohne beabsichtigte Entscheidung und einen, in dem die dokumentierte Rückgabe eine konkrete Wirkung auslösen soll. Kontrollieren Sie jeweils:

  • Erhält das Skript die erwartete Eingabe?
  • Ist die Ausgabe formal gültig und enthält sie die vorgesehenen Felder?
  • Stimmt der Exitstatus mit dem dokumentierten Verhalten überein?
  • Ist in der Diagnose erkennbar, ob Claude Code die Rückgabe verarbeitet hat?

Unterscheiden Sie diese Ergebnisse ausdrücklich: Hook nicht ausgewählt, Handler konnte nicht starten, Skript ist fehlgeschlagen, Rückgabe ist ungültig oder die gewünschte Entscheidung wurde nicht angewendet. Ein einzelner allgemeiner Fehlerhinweis verschleiert genau die Stelle, die Sie finden müssen. Erfassen Sie außerdem Folgefehler separat: Ein späterer Tool-Aufruf oder CI-Schritt kann scheitern, obwohl der Hook korrekt ausgeführt wurde.

Für Blockaden gilt eine zusätzliche Sicherheitsgrenze. Eine Hook-Rückgabe ist keine Isolation des Betriebssystems. Beschränken Sie Dateizugriff und Kontorechte unabhängig davon, prüfen Sie Berechtigungen gesondert und verlangen Sie bei riskanten Änderungen gegebenenfalls eine menschliche Freigabe. Die Hook-Konfiguration kann deterministische Prüfungen unterstützen, aber sie macht einen Prozess nicht automatisch sicher.

6. Xcode-Prüfung unabhängig abnehmen und Fehler reproduzieren

Verknüpfen Sie Formatprüfung, Sitzungsende und CI-Abnahme nicht zu einem undurchsichtigen Gesamtschritt. Ein Hook nach einer Dateiänderung kann beispielsweise eine Formatprüfung anstoßen. Eine Prüfung am Sitzungsende kann einen weiteren Kontrollschritt übernehmen. Der formale Nachweis eines Xcode-Tests sollte jedoch aus dem tatsächlichen Testlauf mit nachvollziehbarem Status und Ergebnis stammen.

Apple beschreibt in der Dokumentation zum Ausführen von Tests und Interpretieren der Ergebnisse, wie Testergebnisse zu beurteilen sind. Für automatisierte Aufrufe sind außerdem der Xcode-Befehlszeilenleitfaden und Apples Archivleitfaden zu Automatisierung und SSH relevant. Verwenden Sie die Materialien des tatsächlichen Testlaufs: Kommando, Rückgabestatus und Testresultat müssen dem CI-Schritt zugeordnet werden können.

Nehmen Sie die Kette mit kontrollierten Erwartungen ab:

  • Ein erwarteter Trigger muss im Diagnoseverlauf sichtbar werden.
  • Ein erfolgreicher Prüffall muss die erwartete Freigabe liefern.
  • Ein absichtlich fehlerhafter Prüffall muss die vorgesehene Ablehnung oder Fehlermeldung erzeugen.
  • Nach einem Neustart muss derselbe Startkontext erneut geprüft werden.

Führen Sie diese Fälle getrennt aus und halten Sie fest, ob der Hook oder der nachfolgende Test verantwortlich war. Ein Hook, der einen Test startet, belegt nicht automatisch, dass CI das Testergebnis als Build-Kriterium ausgewertet hat. Die verbindliche Abnahme gehört deshalb in einen kontrollierten CI-Schritt, der die Ergebnisdaten speichert und den Build anhand der vereinbarten Regel akzeptiert oder zurückweist.

Option Geeignet, wenn Vorteil Grenze
Hook für eine lokale Vorprüfung Sie eine deterministische Prüfung beim passenden Ereignis ausführen möchten Schnelle Rückmeldung im Arbeitsablauf Kein Ersatz für Host-Berechtigungen oder CI-Nachweis
Xcode-Test als CI-Schritt ein reproduzierbares, prüfbares Testergebnis erforderlich ist Testlauf und Abnahme lassen sich getrennt protokollieren Erfordert eine korrekt konfigurierte CI-Umgebung
Betriebssystemrechte und Freigabeprozess Sie Zugriffe oder riskante Aktionen begrenzen müssen Sicherheitskontrolle unabhängig vom Hook Verhindert nicht automatisch fachliche Testfehler

Entscheiden Sie nach dem Befund: Korrigieren Sie Einstellungen, wenn die falsche Quelle geladen wurde; passen Sie Ereignis oder Matcher an, wenn der Trigger nicht passt; beheben Sie Pfad, Interpreter oder Rechte, wenn das Skript nicht starten kann. Ist nur die verbindliche Testentscheidung unklar, verschieben Sie diese in einen kontrollierten CI-Schritt, statt den Hook mit zusätzlichen Aufgaben zu überladen.

Häufige Fragen zur Hook-Fehlersuche

Warum bleibt ein Hook auf dem Remote-Mac vollständig aus?

Prüfen Sie zuerst, ob das erwartete Ereignis im Sitzungsverlauf erscheint und ob die aktive Konfiguration zu diesem Projekt und Konto gehört. Danach testen Sie den Matcher mit einer einzelnen Aktion. Erst wenn Ereignis und Matcher passen, untersuchen Sie Startberechtigung, Interpreter und Abhängigkeiten. Eine Neuinstallation ist kein sinnvoller erster Schritt, solange diese Schichten nicht geprüft sind.

Welche Hooks-Konfiguration gilt in einer SSH- oder CI-Sitzung?

Vergleichen Sie Konto, Arbeitsverzeichnis und erreichbare Einstellungsdateien im tatsächlichen Prozess. Benutzerbezogene Einstellungen können einem Dienstkonto fehlen; Projekteinstellungen setzen voraus, dass der Prozess im passenden Projektkontext startet. Prüfen Sie auch lokale und verwaltete Vorgaben. Dokumentieren Sie nur die verwendete Quelle und nötige Pfade, nicht vertrauliche Konfigurationswerte.

Wie erkennen Sie einen Fehler im PreToolUse-Matcher?

Reduzieren Sie den Test auf ein Ereignis und einen Tool-Aufruf. Prüfen Sie in der Diagnose, ob das Ereignis sichtbar ist und ob der konfigurierte Toolname sowie die Matcher-Felder zum tatsächlichen Aufruf passen. Fehlt das Ereignis, liegt die Ursache vor der Matcher-Auswertung. Ist es sichtbar, aber der Handler wird nicht gewählt, untersuchen Sie die Filterbedingungen einzeln.

Was hilft bei fehlenden Befehlen im Hook unter SSH?

Ermitteln Sie PATH, Interpreter und Arbeitsverzeichnis im Prozess, der den Hook startet. Die Umgebung einer interaktiven SSH-Shell ist nicht automatisch die Umgebung eines Dienstkontos. Verwenden Sie bei Bedarf einen expliziten Programmpfad und definieren Sie notwendige Umgebungswerte für den Hook. Prüfen Sie zusätzlich Dateirechte und Abhängigkeiten, ohne Zugangsdaten in Protokolle zu schreiben.

Reicht ein Stop Hook als Nachweis für bestandene Xcode-Tests?

Nein. Ein Hook kann eine Prüfung anstoßen, aber die Abnahme sollte das tatsächliche Testergebnis aus dem Xcode-Lauf auswerten. Erfassen Sie Testbericht und Rückgabestatus im CI-Schritt und lassen Sie die CI-Regel über den Build entscheiden. So bleiben Hook-Ausführung, Testergebnis und Freigabe voneinander unterscheidbar und später nachvollziehbar.

Wenn Einstellungen, Matcher und Skriptumgebung korrekt sind, aber der Fehler nur im Remote- oder Runner-Kontext auftritt, ist eine kontrollierte Prüfung auf einem echten macOS-System sinnvoller als eine weitere Änderung auf Verdacht. Für die Planung eines solchen Setups können Sie die MACCOME-Angebotsübersicht und die Informationen zum Mac mini bestellen heranziehen. Eine gemietete Mac-Umgebung eignet sich besonders, wenn Sie für einen begrenzten Projektzeitraum einen reproduzierbaren macOS-Testkontext benötigen. Ihre bestehende Linux- oder Windows-Umgebung kann dagegen bei plattformneutralen Builds günstiger und einfacher bleiben; ein eigener Mac ist sinnvoller, wenn Sie dauerhaft hohe Last oder direkten physischen Gerätezugriff benötigen. Prüfen Sie vor einer Miete, ob Konto, Hook-Konfiguration, Testdaten und CI-Abnahme im gewünschten Ablauf tatsächlich zusammenpassen.