Dépannage

Claude Code

Claude Code est introuvable

Symptôme. L’écran d’accueil dit « Claude Code est introuvable sur ce poste ». Le Kanban affiche « Claude Code introuvable — aucun ticket ne démarre », et Réglages › À propos « Claude Code introuvable ».

Cause. Escouade cherche claude dans cet ordre :

1. Le chemin de Réglages › Claude Code, champ « Chemin de l’exécutable », quand il est rempli. S’il est rempli, il décide seul : un chemin faux donne « introuvable », même si claude est dans le PATH.
2. Sinon, le PATH, puis les emplacements habituels des installeurs. Sous Windows : %USERPROFILE%\.local\bin\claude.exe, %USERPROFILE%\.claude\local\claude.exe et %USERPROFILE%\AppData\Roaming\npm\claude.cmd. Sous macOS et Linux : ~/.local/bin/claude, ~/.claude/local/claude, /opt/homebrew/bin/claude et /usr/local/bin/claude.
3. Sous Windows, à défaut, un Claude Code installé dans WSL (voir plus bas).

Solution. Installe Claude Code et connecte-le, ou indique son chemin dans Réglages › Claude Code (voir les réglages Claude Code). Le champ accepte ~ pour ton dossier personnel, et sous Windows on peut y omettre .exe ou .cmd. La ligne sous le champ répond tout de suite : « Trouvé : … » avec le chemin retenu, ou « Introuvable. Indique le chemin de claude.exe, … ». Vide le champ pour revenir à la détection automatique (« vide = détection automatique »).

Un compte Claude peut avoir son propre exécutable (Réglages › Comptes Claude, champ « Exécutable », « Celui des réglages » par défaut). Un chemin qui existe mais ne se lance pas donne « impossible de lancer » suivi de ce chemin.

Claude Code est introuvable quand l’app démarre depuis le Finder (macOS)

Symptôme. claude répond dans le Terminal, mais Escouade, ouverte depuis le Finder ou le Dock, ne le trouve pas, ni git ou node si tu les as installés avec Homebrew.

Cause. macOS donne aux apps lancées depuis le Finder ou le Dock un PATH minimal, pas celui de ton terminal. Au démarrage, Escouade le complète avec celui de ton shell de connexion (elle l’interroge par $SHELL -ilc), puis ajoute /opt/homebrew/bin, /usr/local/bin et ~/.local/bin. Elle n’attend le shell que cinq secondes : un profil qui demande une saisie, ou qui met plus longtemps, annule cette étape. La même chose vaut pour un lanceur de bureau sous Linux.

Solution. Indique le chemin complet de claude dans Réglages › Claude Code (which claude dans un terminal le donne), ou allège le profil de ton shell pour qu’il réponde vite.

Claude Code est installé dans WSL

Symptôme. Claude Code n’est installé que dans WSL, et Escouade ne le trouve pas, ou un agent ne peut pas travailler dans un dossier.

Cause. Sous Windows, Escouade ne regarde dans WSL que si Windows n’a pas de claude. Elle cherche dans la distribution de Réglages › Terminaux (champ « Distribution WSL », « vide = distribution par défaut »), à ~/.local/bin/claude, ~/.claude/local/claude, /usr/local/bin/claude et /usr/bin/claude. Cette recherche peut démarrer la distribution et prendre quelques secondes.

Solution. Indique le chemin dans Réglages › Claude Code, sous l’une de ces formes :

• ~/.local/bin/claude
• /home/<utilisateur>/.local/bin/claude
• \\wsl.localhost\<distribution>\home\<utilisateur>\.local\bin\claude

La ligne sous le champ confirme : « Trouvé dans WSL (Ubuntu) : /home/ada/.local/bin/claude », par exemple. Escouade lance alors claude par wsl.exe, dans le dossier de l’agent (vu de WSL, /mnt/c/…), et lit ses sessions et sa connexion dans le dossier personnel Linux. Un dossier de projet que WSL ne peut pas atteindre (un partage réseau, le dossier d’une autre distribution) est refusé : « Le dossier … n’est pas joignable depuis WSL (…) : le Claude Code qui y est installé ne peut pas y travailler. »

Les outils MCP et le suivi de la vue Claude Code ne marchent pas depuis WSL

Symptôme. Sous le champ du chemin, Réglages › Claude Code affiche : « Le réseau de WSL est en NAT : le serveur MCP d’Escouade et le suivi de la vue Claude Code ne joignent pas l’app. »

Cause. En mode NAT, WSL n’est pas sur le réseau de Windows : le serveur MCP d’Escouade et les hooks de la vue Claude Code, qui écoutent sur le 127.0.0.1 de Windows, lui sont hors de portée.

Solution. Passe WSL en réseau miroir. Dans %UserProfile%\.wslconfig :

[wsl2]
networkingMode=mirrored

Puis, dans un terminal Windows, lance wsl --shutdown et relance Escouade.

Une variable du profil du shell n’arrive pas à Claude Code dans WSL

Symptôme. Claude Code, dans WSL, ne voit pas une variable posée dans ~/.profile ou ~/.bashrc.

Cause. Escouade le lance sans le profil du shell : ces fichiers ne sont pas lus.

Solution. Le proxy de Réglages › Réseau, lui, est transmis à Claude Code dans WSL. Pour une autre variable, définis-la côté Windows (dans les variables d’environnement de ton compte), ajoute son nom à la variable Windows WSLENV (les noms s’y séparent par :) et relance Escouade. Escouade garde ta valeur de WSLENV et y ajoute les variables qu’elle transmet elle-même.

Réseau

Escouade est derrière un proxy

Symptôme. Les quotas, les intégrations, les mises à jour ou Claude Code n’arrivent pas à se connecter depuis un réseau d’entreprise.

Solution. Dans Réglages › Réseau, renseigne « Proxy HTTP(S) » (par exemple http://utilisateur:motdepasse@proxy:3128) et, si besoin, « Exclusions » (la liste NO_PROXY, séparée par des virgules). Le proxy est transmis aux processus Claude Code, à la lecture des quotas, aux intégrations et aux mises à jour. Pour un agent, il s’applique au prochain (re)démarrage de son processus. Pour que les terminaux intégrés, les commandes de lancement et les commandes de préparation et de démontage des worktrees l’utilisent aussi, active « Appliquer aussi le proxy aux terminaux intégrés » (désactivé par défaut). Voir les réglages Réseau.

Un certificat d’entreprise fait échouer les connexions

Symptôme. Une erreur « UnknownIssuer », ou un autre échec TLS, pour les intégrations, les quotas, les mises à jour ou Claude Code.

Cause. Un proxy d’entreprise déchiffre le trafic avec un certificat que personne ne reconnaît. Les requêtes d’Escouade (intégrations, quotas, mises à jour) font confiance aux certificats reconnus et à ceux installés sur le système, celui d’un proxy d’entreprise le plus souvent. Claude Code, lui, a sa propre liste.

Solution. Installe le certificat de l’entreprise dans le système : Escouade lui fait alors confiance pour ses propres requêtes. Claude Code a sa propre liste : pour lui, ou si tu ne peux pas installer le certificat, active « Ignorer la vérification des certificats TLS » (Réglages › Réseau, groupe « Certificats »). Le réglage s’applique aux intégrations, aux quotas, aux mises à jour, aux processus Claude Code (au prochain démarrage de leur processus) et aux commandes que lancent les agents (npm, node…).

Quotas et limite d’usage

Les quotas ne s’affichent pas

Symptôme. Dans la barre d’état, 5h et 7j ont une barre vide et un « — » à la place du décompte, et l’infobulle dit « Quota indisponible ». Dans Réglages › Comptes Claude, le compte dit « Pas connecté », « Pas connecté par un compte claude.ai (clé d’API ?) » ou « Connexion expirée : relance Claude Code pour ce compte. »

Causes possibles.

• Les quotas sont ceux d’un abonnement claude.ai : Escouade les lit avec la connexion que Claude Code garde pour le compte. Un Claude Code utilisé avec une clé d’API n’en a pas.
• La connexion a expiré.
• Anthropic n’est pas joignable (réseau, proxy, certificat : voir plus haut). Les dernières valeurs restent affichées, et Escouade réessaie à la lecture suivante, environ toutes les cinq minutes.
• Sous macOS, Claude Code garde sa connexion dans le trousseau. Si tu refuses l’accès quand macOS le demande, Escouade ne le redemande pas avant dix minutes.

Solution. Dans Réglages › Comptes Claude, « Se connecter… » (ou « Se reconnecter… ») ouvre un terminal où Claude Code te connecte (commande /login s’il ne le propose pas). Pour Principal, c’est la connexion de ton propre Claude Code. Voir les comptes Claude.

Un agent s’est arrêté sur la limite d’usage

Symptôme. La carte « Le tour s’est terminé en erreur » affiche le message de Claude Code sur la limite d’usage, et l’agent s’arrête.

Cause. La fenêtre de 5 h ou la semaine de ton abonnement est épuisée.

Solution. Ce que fait l’app dépend de tes réglages :

• Reprise automatique. Le réglage « Reprise automatique après la limite d’usage » (Réglages › Claude Code, activé par défaut) envoie « continue » une fois le quota réinitialisé. Quand Claude Code indique l’heure de remise à zéro, la carte dit « Reprise automatique » suivi du moment, avec un bouton « Annuler la reprise ».
• Un autre compte. Avec plusieurs comptes, le bouton « Reprendre sur Pro » (avec le nom d’un autre compte), et son menu « Reprendre sur un autre compte », font repartir l’agent avec sa session sur un autre compte. Les comptes inactifs, pas connectés ou au-delà de « Pause au-delà du quota » n’y figurent pas.
• Les agents de ticket attendent la remise à zéro de leur compte, sauf si tu actives « Reprendre sur un autre compte un agent de ticket arrêté par la limite » (Réglages › Claude Code, avec plusieurs comptes).

Pour ne pas arriver à la limite, le pilote auto se met en pause avant, au seuil « Pause au-delà du quota ».

Agents

Un agent s’est arrêté

Symptôme. L’agent passe en « Erreur ». La conversation dit « Claude Code s’est arrêté (code N) », suivi de ce que Claude Code a écrit en sortant, et un bandeau ajoute « L’agent s’est arrêté. Envoie un message pour relancer Claude sur la même session. »

Cause. Le processus Claude Code de l’agent s’est terminé de lui-même. Le message qu’il a laissé dit le plus souvent pourquoi (connexion, proxy, version…).

Solution. Envoie un message : Escouade relance Claude sur la même session. Un processus arrêté exprès n’est pas une erreur : Escouade arrête les processus inactifs après un délai (Réglages › Claude Code, « Arrêter les processus Claude inactifs après », 30 minutes par défaut, 0 pour jamais) et les relance à la prochaine action.

Session Claude introuvable

Symptôme. Une notice dit « Session Claude introuvable : une nouvelle session sera démarrée au prochain message. »

Cause. Escouade a relancé l’agent sur sa session, mais Claude Code ne la connaît plus (par exemple parce que le dossier de configuration du compte a été vidé ou changé).

Solution. Il n’y a rien à faire : le message suivant démarre une nouvelle session. La conversation reste affichée dans Escouade, mais Claude n’en a plus le contexte.

Worktrees

La préparation d’un worktree échoue

Symptôme. La conversation de l’agent affiche « La préparation du worktree a échoué sur npm ci (code 1). », suivie des dernières lignes de la sortie et de « Sortie complète » avec un chemin.

Cause. Une commande de préparation du projet a échoué (Réglages › Projets, groupe « Worktrees », section « À l’ouverture d’un worktree »). Escouade les lance dans l’ordre et s’arrête à la première qui échoue. La raison est entre parenthèses : « code 1 », « arrêtée », « pas finie en 20 min » (une commande dispose de 20 minutes), « ne démarre pas » suivi de la cause, ou « le dossier … n’existe pas dans le worktree ».

Solution. Lis la sortie complète dans ~/.escouade/logs/<agent>-setup.log : chaque étape y a son nom et sa fin. Corrige la commande dans les réglages du projet (voir les réglages des projets), ou lance-la à la main dans un terminal ouvert dans le worktree. Les commandes reçoivent ESCOUADE_PROJECT_DIR, ESCOUADE_WORKTREE_DIR et ESCOUADE_BRANCH. L’agent reste utilisable ; pour un agent de ticket, l’échec est ajouté à son premier message, et Claude doit faire le nécessaire pour pouvoir travailler et tester. Le log est remplacé à chaque nouvelle préparation, et disparaît avec l’agent.

À la suppression d’un agent, une commande de démontage qui échoue est signalée de la même façon : « Agent supprimé, mais le démontage du worktree a échoué sur … ». L’agent est supprimé quand même.

Git

Une commande git est interrompue

Symptôme. Un message dit « git status interrompu : toujours pas terminé après 120 s » (la commande et la durée changent), dans l’aperçu d’un commit, un merge, une synchronisation…

Cause. Escouade arrête une commande git qui ne finit pas, pour que la fenêtre ne reste pas bloquée : une lecture (statut, log, diff…) au bout de 2 minutes, une commande qui joint le dépôt distant (push, pull, fetch) au bout de 3 minutes (1 minute pour le fetch lancé en arrière-plan), et une commande qui lance les hooks de git (commit, merge, rebase, changement de branche) au bout de 30 minutes.

Solution. Lance la même commande à la main dans un terminal ouvert dans le dossier du projet pour voir ce qui la bloque (un hook, les identifiants du dépôt distant, le réseau), puis refais l’action dans Escouade.

Notifications

Les notifications n’apparaissent pas

Symptôme. Pas de notification, ou pas de son, quand un agent pose une question, termine ou tombe en erreur.

Causes possibles.

• Le type est désactivé. Dans Réglages › Notifications, « Me prévenir pour » liste « Questions et autorisations », « Tâches terminées », « Erreurs » et « Tickets (prêt à tester, bloqué) ». Un type désactivé n’a ni notification système ni carillon ; l’onglet, la carte et la barre des tâches (le Dock sous macOS) signalent toujours l’agent.
• La notification système n’apparaît que si la fenêtre d’Escouade n’est pas au premier plan (affichée, active et non réduite) : au premier plan, seul le carillon sonne. Elle demande aussi que l’interrupteur du groupe « Canaux » soit activé (« Notifications Windows quand l’app n’est pas au premier plan », « Notifications macOS… » sous macOS).
• Le son est coupé : le bouton « ♪ » de la barre d’état et le réglage « Son activé » le commandent, et « Tester le son » l’essaie.
• Sous Linux, Escouade n’envoie pas de notification système. Le carillon est joué par paplay : sans lui, pas de son.
• Vérifie aussi que le système autorise les notifications d’Escouade, et qu’un mode « ne pas déranger » ne les masque pas.

Voir les notifications.

Données et jetons

Un fichier de données est illisible

Symptôme. Escouade démarre sans ses projets, ou avec ses réglages par défaut.

Cause. state.json ou settings.json (ou integrations.json, sync-queue.json) n’était pas du JSON valide. Escouade en a gardé une copie sous un nom comme state.broken.json et a démarré avec les valeurs par défaut pour ce fichier.

Solution. Ouvre la copie pour retrouver ce qu’elle contenait, par exemple la liste des projets. app.log dit quel fichier posait problème. Voir les données locales.

Le trousseau du système est illisible

Symptôme. Réglages › Intégrations dit « Trousseau du système illisible : relance Escouade ou reconnecte le compte. » ou « Trousseau du système indisponible : le jeton reste dans ~/.escouade/integrations.json. »

Solution. Relance Escouade ; si le message revient, reconnecte le compte (le jeton est alors enregistré de nouveau). Dans le second cas, le jeton reste dans integrations.json, lisible par toi seul sous macOS et Linux.

Journal et signalement

Où est le journal de l’app

Le journal est ~/.escouade/app.log (C:\Users\<toi>\.escouade\app.log sous Windows). Chaque ligne porte la date, le niveau et le texte : démarrage et version, arrêts d’agents, erreurs, migrations, mises à jour. Quand il dépasse environ 5 Mo, le démarrage suivant le range sous le nom app.old.log. Tout éditeur de texte l’ouvre.

Signaler un bug

Ouvre une issue sur GitHub avec :

• la version d’Escouade (Réglages › À propos, « Escouade 1.7.5 » par exemple) et ton système (Windows, macOS ou Linux, et sa version) ;
• ce que tu faisais, ce que tu attendais, ce qui s’est passé, et une capture si elle aide ;
• les lignes utiles de app.log. Relis-les avant de les joindre : elles peuvent citer des chemins de tes dossiers et des noms de projets. Ne colle jamais un jeton.