← Tous les articles

claude respawn : quand une session en arrière-plan rate ta mise à jour de plugin.

2026-09-25 · 6 min de lecture · par Nabil BA-MOH

Tu mets à jour un plugin. Une nouvelle session Claude Code a le changement. La session en arrière-plan dans laquelle tu bosses depuis ce matin ne l’a pas, et /reload-plugins n’y change rien. La commande qu’il te faut, c’est claude respawn <id> : elle redémarre la session, garde la conversation, et la relance à neuf sur ce qui est installé maintenant.

La doc officielle présente respawn comme le moyen de passer les sessions sur un nouveau binaire Claude Code. Elle ne prévient pas qu’un UUID de session ne marche pas, qu’un thème de plugin ne fait pas partie de ce que /reload-plugins recharge, ni ce que veut dire le refus lié au dossier personnel. Voici ce qu’on a mesuré le 25 septembre 2026.

Ce qui s’est passé

L’essentiel de notre travail dans Claude Code tourne dans des sessions en arrière-plan : lancées avec claude --bg, listées par claude agents. Notre plugin, Klyr, a livré un thème clair via son dossier experimental.themes.

• Un claude interactif tout neuf affichait le nouveau thème dans /theme.
• La session en arrière-plan, non. Pas même après /reload-plugins.
• /exit n’a rien changé. Ça, c’est documenté : dans une session en arrière-plan, /exit détache et laisse la session tourner. Il ne redémarre jamais rien.
• claude respawn <id> a réglé le problème. La session est revenue avec sa conversation, et le thème était dans /theme.

Notre propre erreur mérite d’être dite : on a tourné en rond avec « recharge encore » et « ouvre un nouveau terminal » avant d’aller chercher la commande de cycle de vie. Un nouveau terminal te donne une nouvelle session, pas celle dans laquelle tu travailles.

Pourquoi /reload-plugins ne suffisait pas

La doc dit clairement qu’une session en cours garde les versions de plugin qu’elle a chargées, et que /reload-plugins ou une nouvelle session fait entrer les changements. Ce qu’elle ne précise pas, c’est qu’un rechargement n’est pas un redémarrage. Regarde ce qu’il affiche :

Reloaded: N plugins · N skills · N agents · N hooks · N plugin MCP servers · N plugin LSP servers

Pas de thèmes. La référence sur le chargement des plugins admet déjà qu’un composant demande un vrai redémarrage : les monitors. Sur notre machine, un thème de plugin s’est comporté pareil dans une session en arrière-plan. (On n’a pas testé de rechargement dans une session interactive, donc on n’affirme rien sur ce cas.)

Ne te laisse pas induire en erreur par la page des thèmes non plus : ~/.claude/themes/ est surveillé en direct, mais c’est ton propre dossier de thèmes. Le thème d’un plugin vit dans le plugin.

La règle qu’on suit maintenant : si un rechargement ne montre pas le changement, fais un respawn.

Ce que fait vraiment chaque geste

Passe l’id court, pas l’UUID de session

claude agents --json donne deux ids à chaque session en arrière-plan :

• id : l’id de job court en 8 caractères hexa, aussi le nom du dossier sous ~/.claude/jobs/ ;
• sessionId : l’UUID complet de la conversation, celui que prend claude --resume.

La doc présente l’id court comme celui à utiliser depuis le shell, et l’indique pour attach, logs et stop. Elle ne prévient pas qu’un sessionId échoue, ni que l’id court n’est pas toujours le début de l’UUID. On a vérifié : respawn compare son argument au début de l’id court. Un sessionId ne marche pas.

Le piège facile, c’est de croire que l’id court n’est que les 8 premiers caractères de l’UUID. Souvent, c’est le cas. Pas pour les sessions reprises : sur notre Mac (Claude Code 2.1.282), 5 de nos 14 sessions en arrière-plan avaient un id qui n’est pas le début de leur sessionId. Lis toujours l’id dans claude agents --json.

Quelles sessions sont obsolètes ?

Il n’y a pas de version de plugin dans claude agents --json, donc aucun champ ne dit « cette session tourne sur un vieux plugin ». Ce que tu peux faire, c’est comparer deux dates : quand la session a démarré, et quand le plugin a été mis à jour pour la dernière fois. Une session vivante démarrée avant la mise à jour tourne peut-être encore sur l’ancienne version.

import json, subprocess, sys
from datetime import datetime

def cli(*args):
    return json.loads(subprocess.run(["claude", *args, "--json"], capture_output=True, text=True).stdout)

def epoch_ms(iso):
    return datetime.fromisoformat(iso.replace("Z", "+00:00")).timestamp() * 1000

plugin = sys.argv[1]
updated = max((epoch_ms(p.get("lastUpdated") or p["installedAt"])
               for p in cli("plugin", "list") if p["id"] == plugin), default=None)
if updated is None:
    sys.exit(f"{plugin} is not installed")

for s in cli("agents"):
    if s["kind"] == "background" and "pid" in s and s["startedAt"] < updated:
        print(s["id"], s["status"], s.get("name", ""))

Lance-le avec python3 stale.py <plugin>@<marketplace>. Il ne fait que lire. Deux détails qu’il gère pour toi :

• startedAt est en millisecondes epoch, lastUpdated est une date ISO. Compare-les bruts et toutes les sessions semblent obsolètes, ou aucune.
• pid et status n’apparaissent que tant que le processus est vivant. Une entrée sans pid n’a rien en mémoire qui puisse être obsolète, donc le script la saute.

C’est une heuristique, pas une vérification de version : un /reload-plugins rafraîchit déjà la plupart des composants. Le script te dit quelles sessions regarder. Sur notre Mac, il n’en a trouvé aucune : 5 sessions dataient d’avant la dernière mise à jour, et aucune n’avait de processus vivant.

Trois pièges avant de faire un respawn

1. --all t’inclut. claude respawn --all redémarre toutes les sessions en cours, celle où tu tapes aussi. Lance-le depuis un simple shell. Ou fais-les une par une, celle où tu es en dernier.
2. Vérifie d’abord status. busy veut dire que la session est au milieu d’un tour. Laisse-la finir, ou accepte de la couper.
3. Les sessions dans ton dossier personnel peuvent refuser. Une session ancrée dans ton dossier personnel peut répondre :

   Workspace not trusted. The home directory is trusted one session at a time — start this from an interactive terminal there, or from a project directory.

   Ce message n’est pas sur la page des erreurs de la doc (seul son cousin Remote Control y est). Le message donne lui-même la sortie : un terminal interactif ouvert dans ton dossier personnel, ou un dossier de projet. La bonne habitude, c’est la deuxième : garde les sessions longues dans un dossier de projet.

Sur Windows

Même commande sur Windows 11 natif (Claude Code 2.1.274) : claude respawn <id>|--all. Les entrées en arrière-plan de claude agents --json portent id, sessionId, name, cwd, kind, startedAt, state, plus pid et status tant qu’elles sont vivantes. Les jobs vivent sous %USERPROFILE%\.claude\jobs\<id>\.

Une différence sur laquelle tu vas tomber : le tableau simple de claude agents a besoin d’un vrai terminal (TTY). Depuis un script ou un pipe, utilise claude agents --json. Le script plus haut n’appelle que les deux commandes JSON. On l’a lancé sur macOS.

Le principe, en une ligne

Une session en arrière-plan est un processus qui vit longtemps : elle garde ce qu’elle a chargé jusqu’à ce que quelque chose la redémarre. Quand une mise à jour n’apparaît pas après un rechargement, n’ouvre pas un autre terminal. Trouve l’id court et fais un respawn.

Les sessions en arrière-plan ont aussi leurs propres règles de connexion : Sessions Claude Code en arrière-plan et authentification MCP.

FAQ