Que faire si les hooks de Claude Code ne s’exécutent pas sur un Mac distant ? Guide de dépannage 2026

Verdict — adapté si vous utilisez Claude Code par SSH sur un Mac distant : vérifiez d’abord l’événement et son matcher, puis le lancement du script, l’environnement distant et enfin les sorties et le code de retour. Ne concluez pas à un défaut de Claude Code et ne désactivez pas les contrôles de permissions avant d’avoir isolé la cause.

Cet article s’adresse aux développeurs qui utilisent Claude Code sur un Mac distant via SSH et veulent repérer à quelle étape leur hook échoue. Il concerne aussi les équipes qui partagent une configuration de hooks ou exécutent des vérifications, des tâches de construction et des traitements audio ou vidéo dans un environnement macOS distant.

Distinguer un événement manquant d’un script sans effet

Un hook peut sembler « ne pas s’exécuter » alors que le problème se situe à différents endroits : l’action ne déclenche pas l’événement configuré, le matcher ne correspond pas, le processus ne démarre pas, ou le script démarre mais n’obtient pas le résultat attendu. Ces situations ne se corrigent pas de la même façon. Modifier les permissions avant de savoir laquelle est en cause élargit inutilement le risque.

Commencez par consigner la version de Claude Code, le type de session, la configuration pertinente et l’opération exacte qui reproduit le problème. Si vous comparez une session SSH et une session locale, gardez la même action et le même projet. Cette comparaison évite d’attribuer à un changement de configuration une différence qui vient en réalité du contexte de lancement.

Pour rendre le diagnostic observable, utilisez temporairement un hook minimal qui écrit un marqueur dans un fichier de diagnostic situé dans le projet, puis quitte sans modifier les fichiers de travail. Il permet de vérifier si l’exécution a eu lieu sans faire dépendre le test d’un formateur, d’un compilateur ou d’un autre outil externe. Les événements, les réglages et les résultats des hooks sont décrits dans la référence officielle des hooks.

Consignez ensuite ce que le test permet effectivement d’établir :

• Aucun marqueur n’apparaît : vérifiez l’événement, le matcher et le fichier de configuration chargé.
• Le marqueur apparaît, mais le traitement attendu manque : le déclenchement a probablement eu lieu ; examinez le script, les arguments, son répertoire courant et son résultat.
• Le script écrit une erreur ou renvoie un code non nul : diagnostiquez son exécution avant de modifier les réglages de l’outil.

Cette séparation est utile dans un environnement de développement Mac distant : elle transforme un symptôme ambigu en vérifications ciblées, sans reconfiguration générale du projet.

Pourquoi l’événement ou le matcher peut-il manquer ?

Le nom d’un hook ne suffit pas à déterminer quand il s’exécute. Il faut que l’événement configuré corresponde à l’étape réellement effectuée, et que le matcher soit adapté au contexte prévu par cette configuration. Consultez la référence des événements et des hooks pour vérifier la sémantique actuelle, plutôt que de déduire le comportement du nom d’une option ou d’un exemple trouvé ailleurs.

Examinez également la portée du réglage. Claude Code documente plusieurs fichiers et niveaux de configuration : un réglage du projet n’a pas nécessairement le même périmètre qu’un réglage utilisateur. Vérifiez le fichier effectivement présent sur le Mac distant et la manière dont votre session est lancée. La documentation des réglages précise les formats et les emplacements à contrôler.

Un test utile ne doit pas effectuer un déploiement, supprimer des fichiers ou lancer une longue construction. Il doit seulement montrer que l’événement retenu est atteint. Si vous soupçonnez un matcher, simplifiez-le temporairement pour correspondre au cas testé, mais conservez la règle d’origine à portée de main afin de pouvoir la restaurer et vérifier ensuite les cas limites.

Le processus démarre-t-il réellement sur le Mac distant ?

Quand l’événement semble correct, vérifiez les conditions concrètes de lancement. Le chemin configuré doit exister sur la machine distante, pas seulement sur votre poste local. Le shebang doit désigner un interpréteur disponible sur ce Mac, et le fichier doit être exécutable si la configuration l’invoque directement. La documentation officielle consacrée aux hooks fournit les exemples de configuration et les modes d’entrée à utiliser comme référence ; comparez votre cas à ces exemples au lieu de supposer un comportement non documenté.

Dans la session SSH où vous reproduisez le problème, contrôlez le chemin et le droit d’exécution :

ls -l /chemin/du/projet/scripts/controle.sh
head -n 1 /chemin/du/projet/scripts/controle.sh
test -x /chemin/du/projet/scripts/controle.sh

L’absence de sortie de test n’est pas, à elle seule, une preuve suffisante : vérifiez son code de retour ou utilisez une condition explicite. Si votre configuration lance le script par l’intermédiaire d’un interpréteur, contrôlez aussi que cet interpréteur est présent et que la commande correspond exactement à la structure documentée.

Pour séparer un problème de configuration Claude Code d’un problème propre au script, exécutez celui-ci depuis la même session distante et avec le même utilisateur. S’il échoue aussi dans le terminal SSH, corrigez d’abord le script ou ses dépendances. S’il fonctionne dans le terminal mais pas dans le hook, comparez le répertoire courant et les variables d’environnement disponibles au processus.

À retenir : n’accordez pas un droit d’écriture plus large que nécessaire pour faire disparaître une erreur. La documentation de sécurité de Claude Code et celle des permissions doivent guider toute modification qui élargit ce qu’un script ou une commande peut faire.

Les écarts de session SSH et de répertoire de travail

Le succès d’une commande dans un terminal interactif ne prouve pas qu’elle sera trouvée par un hook. Les réglages du shell, le PATH et les variables chargées à l’ouverture d’un terminal peuvent différer du contexte utilisé pour lancer le processus. C’est une cause fréquente de confusion pour les développeurs qui configurent un environnement Mac distant depuis leur poste habituel.

Comparez les deux contextes, sans publier de secrets ni recopier toutes les variables dans un journal :

printf 'PATH=%s\n' "$PATH"
printf 'PWD=%s\n' "$PWD"
command -v brew
command -v xcodebuild

Exécutez ces commandes dans le terminal SSH, puis ajoutez une trace limitée aux valeurs utiles dans le script de diagnostic du hook. Le résultat vous indique si la commande est absente, si son chemin est différent ou si le script démarre depuis un autre dossier. Si le besoin est confirmé, utilisez un chemin explicite vers l’outil, ou préparez le PATH dans le contexte d’exécution documenté par Claude Code. Évitez de dépendre implicitement d’un fichier de configuration interactif que le processus du hook ne charge pas.

Le répertoire courant mérite une vérification distincte : un chemin relatif peut fonctionner dans le terminal depuis la racine du dépôt, mais viser un autre emplacement si le hook est lancé depuis un dossier différent. Pendant le diagnostic, affichez le répertoire et construisez les chemins nécessaires à partir d’une base connue. Retirez ensuite les traces provisoires si elles divulguent des informations sur l’environnement.

La référence officielle des variables d’environnement aide à distinguer les variables prises en charge de celles dont la présence ne doit pas être supposée. Pour évaluer plus largement votre environnement de développement Mac distant, comparez aussi l’accès aux outils macOS et la façon dont la session distante est administrée : un terminal accessible ne garantit pas, à lui seul, que le processus du hook a le même environnement.

Pour les tâches qui s’appuient sur les outils Apple, vérifiez leur disponibilité sur le Mac distant au lieu de considérer qu’un environnement SSH fournit automatiquement l’ensemble de la chaîne de développement. La même prudence s’applique à un formateur, à un outil audio ou à un moteur de rendu : le hook ne peut appeler que les exécutables réellement accessibles dans son contexte.

Sorties, codes de retour et journaux de débogage

Si le script démarre, récupérez séparément sa sortie standard, sa sortie d’erreur et son code de retour. Un code nul est généralement utilisé pour signaler une réussite et un code non nul un échec dans les exemples de scripts et de commandes ; vérifiez cependant le traitement propre au hook et à l’événement concerné dans la référence officielle. Une sortie vide ne signifie pas nécessairement que rien ne s’est exécuté.

Un diagnostic peut, par exemple, exposer temporairement le résultat d’une commande sans modifier le dépôt :

/chemin/du/projet/scripts/controle.sh
status=$?
printf 'code_retour=%s\n' "$status" >&2
exit "$status"

Ce fragment conserve le code de sortie du script afin que l’étape appelante puisse constater son résultat. Il ne remplace pas le format d’entrée ou de sortie exigé par le hook configuré. Si votre hook consomme des données ou doit renvoyer un résultat structuré, comparez sa configuration au format documenté plutôt que d’ajouter arbitrairement du texte à la sortie.

Activez ensuite le débogage selon les indications de la documentation officielle de débogage. Consultez les journaux de la session où le test a été reproduit et recherchez l’événement, le chargement des réglages et l’exécution de la commande. Distinguez un diagnostic écrit dans les journaux d’un résultat destiné à être montré dans la conversation : la façon dont une sortie est traitée dépend du hook et de sa configuration.

Valider la correction sans augmenter le risque

Une fois la cause isolée, validez la correction dans l’ordre où elle sera utilisée : d’abord avec un test sans effet de bord, ensuite avec la tâche réelle du projet. Une tâche de formatage, un test ou une construction permet de vérifier le raccordement à la chaîne macOS, mais ne choisissez pas un script qui efface des fichiers ou publie des artefacts pour effectuer la première validation.

Avant d’utiliser un hook partagé, relisez la commande qu’il lance et les permissions associées. Vérifiez que ses chemins pointent vers le projet voulu, que les variables sensibles ne sont pas écrites dans les journaux et qu’un échec n’entraîne pas une action destructive. Si une commande nécessite une autorisation plus large, déterminez précisément ce qu’elle doit faire et respectez le modèle de permissions documenté ; ne neutralisez pas la protection générale pour contourner un problème d’exécution.

Si vous devez comparer l’accès distant ou clarifier le mode d’accès à une machine, vous pouvez consulter les informations de contact OakVM. Ce recours n’est pas un substitut au diagnostic : les événements, le script et l’environnement doivent rester vérifiables dans votre propre projet.

Questions fréquentes

Pourquoi un hook Claude Code ne se déclenche-t-il pas ?

Vérifiez d’abord que l’opération réalisée correspond à l’événement configuré, puis que son matcher correspond bien à l’outil ou au contexte concerné. Contrôlez aussi le fichier de paramètres chargé par la session. Un test minimal, sans effet sur le projet, permet de distinguer une configuration ignorée d’un script qui échoue après son lancement.

Que vérifier si un hook ne trouve pas une commande en SSH ?

Comparez le PATH et le répertoire courant du processus lancé par Claude Code avec ceux de votre terminal interactif. Vérifiez le chemin réel de l’exécutable sur le Mac distant et, si nécessaire, utilisez un chemin explicite. Ne supposez pas que les réglages de votre shell interactif sont disponibles dans le contexte du hook.

Comment contrôler les droits d’un script et son répertoire de travail ?

Depuis la session distante, vérifiez que le chemin indiqué dans la configuration existe, que le shebang désigne un interpréteur disponible et que le script est exécutable. Ajoutez temporairement une trace sans effet de bord pour consigner le répertoire courant et les informations utiles. Évitez de rendre tout un dossier accessible en écriture pour corriger un seul fichier.

Où trouver les erreurs d’exécution d’un hook Claude Code ?

Commencez par récupérer la sortie standard, la sortie d’erreur et le code de sortie du script. Activez ensuite le mode de débogage documenté par Claude Code et examinez les journaux correspondant à la session et à l’événement. La sortie d’un hook n’est pas nécessairement affichée comme un message de conversation : vérifiez le traitement documenté de son résultat.

La bonne décision consiste à corriger l’étape qui échoue, plutôt qu’à réinstaller l’outil ou à affaiblir ses contrôles. Si votre environnement actuel dépend d’une machine rarement accessible, d’un PATH maintenu à la main et d’une configuration SSH difficile à reproduire, un Mac distant disponible de façon continue peut simplifier l’accès à la chaîne macOS ; cela ne dispense toutefois pas votre équipe de maintenir les hooks, les scripts et leurs permissions. Si vous n’avez besoin que d’un test ponctuel, votre Mac local ou une autre solution adaptée au projet peut suffire. Si votre travail nécessite un environnement macOS accessible pour des vérifications récurrentes, examinez une location de Mac avec OakVM après avoir validé le besoin avec les étapes ci-dessus.

Questions fréquentes