De l’achat dans votre terminal au premier couloir, puis chaque commande pour continuer et retrouver votre chemin.
Ce guide décrit Treelab 1.3.0, la dernière version publiée.
Le texte reste sélectionnable. Vérifiez les chemins avant de coller une commande dans votre terminal.
Préparer le poste
Il vous faut un Mac sous macOS 13 ou plus et au moins un agent de code, Claude Code ou Codex, déjà connecté à votre compte. Les comptes, accès et abonnements de ces outils sont séparés et ne sont pas inclus. S’ils manquent, Git et jq sont installés par l’installeur via Homebrew, et cmux par lab setup, chaque fois après votre accord. gh et ses droits GitHub ne servent qu’à livrer des demandes de fusion.
Dans Terminal, vérifiez la version de macOS et la présence de votre agent : chaque command -v doit afficher un chemin. Si aucun agent n’est trouvé, installez Claude Code ou Codex et connectez-le avant de continuer.
sw_vers -productVersion
command -v claude
command -v codex
Acheter et installer
Collez la commande ci-dessous dans Terminal. L’assistant d’installation, en anglais, avance en quatre temps : Prepare (préparer), Plan, Activate (activer), Start (démarrer). Préparer : vous choisissez vos agents, votre projet et votre objectif ; vos choix restent sur ce Mac. Plan : il propose un premier découpage. Activer : il propose 1 « Buy Treelab » (acheter) ou 2 « Enter a key » (saisir une clé). Acheter ouvre la page de paiement dans votre navigateur ; revenez ensuite au terminal : la clé y arrive, et aussi par e-mail. Si vous avez payé par le lien de paiement du site, choisissez 2 et collez la clé reçue par e-mail (elle commence par tl_key_). Ne payez jamais une seconde fois : relancer la même commande reprend là où vous en étiez.
Un particulier reçoit sa clé immédiatement seulement s’il demande la fourniture avant la fin du délai de rétractation de 14 jours et reconnaît perdre ce droit ; sinon, la clé arrive par e-mail à la fin du délai. L’assistant active ensuite la licence sur ce Mac, installe Git et jq s’ils manquent, télécharge et vérifie Treelab.
Démarrer : il lance lab setup, qui affiche le plan (instructions, skills, agents, hooks, commandes, profil du shell et sauvegardes) et propose cmux séparément s’il manque. Tapez I accept seulement si vous acceptez ces changements ; en cas de refus, rien n’est installé et lab setup --dry-run remontre le plan à tout moment. Enfin, l’assistant enregistre votre projet et ouvre son premier couloir dans cmux, avec votre objectif.
curl -fsS https://treelab.sh/install | /bin/bash
lab setup --dry-run
Vérifier l’installation
Ouvrez un nouveau terminal pour prendre en compte PATH. La commande installée s’appelle treelab ; lab est son nom court quand ce nom est libre. Si lab désigne déjà un autre outil, il est conservé et vous utilisez treelab pour vos appels directs. Les onglets de couloir démarrent l’agent par lab launch : ce lancement automatique suppose que lab désigne Treelab ; sinon, contactez le support avant de poursuivre.
doctor explique chaque contrôle par une NOTE : corrigez chaque rouge puis relancez. Codex demande une approbation unique des hooks (/hooks) ; Claude Code les charge sans geste. Le bilan normal peut contenir des chemins privés : gardez-le sur votre poste.
treelab --version
treelab doctor
command -v lab
Votre premier couloir
Un projet est votre dépôt Git enregistré. Un couloir est une copie de travail isolée sous .worktrees/, destinée à un besoin. Un lot est une étape vérifiable, avec une branche et une fiche ; son objectif (Goal) dit quel résultat doit être prouvé.
À la fin de l’installation, votre premier couloir est déjà ouvert dans cmux : l’agent part de l’objectif choisi pendant la préparation, sans refaire le questionnaire, et rédige le plan du premier lot. Répondez dans cet onglet ; ensuite, lab next ouvre chaque étape avec le Goal de la fiche.
Pour un nouveau besoin dans le même projet, lab new crée un autre couloir ; --brief donne à l’agent le texte de votre besoin. Pour un autre dépôt, lancez lab onboard dans son dossier : il l’enregistre sans toucher à vos fichiers et ouvre un agent dans l’onglet « main » de ce projet.
lab next demo premier
lab new demo second --brief besoin.md
cd /chemin/vers/autre-depot
lab onboard
Du lot à la livraison
Dans l’onglet du couloir : qualifier → planifier → exécuter → vérifier → livrer. Les contrôles sont les tests, le bilan doctor, une revue indépendante et l’essai réel des écrans. Chaque lot est livré par lab merge après contrôles verts ; sa fiche garde les preuves et une Reprise lisible sans la mémoire de l’agent.
next lit l’état et décide de la suite ; il ne fusionne ni ne retire. Après le dernier lot vient la recette : vous essayez le résultat exact, puis l’agent note votre accord avec lab acceptance. close livre alors le dernier lot et retire le couloir, après votre confirmation explicite ; --dry-run liste d’abord tout ce qui l’empêcherait. Un contrôle rouge arrête la livraison jusqu’à correction.
lab plan demo
lab status demo
lab close demo premier --dry-run
lab close demo premier
Mise à jour, retour arrière et retrait
lab next pose seul la dernière version mineure ou corrective, une fois par jour au plus ; une version majeure est seulement annoncée, et auto_update=no dans ~/.lab/config limite tout à l’annonce. lab update fait la même chose à la demande : il télécharge la version avec votre licence, vérifie l’archive et son empreinte, puis bascule. Les sessions d’agent ouvertes gardent leur version.
La version précédente est conservée : lab update --rollback y revient sans réseau. Tout échec finit par RESULT=refused ou interrupted avec la raison et le fichier en cause, et la version en place est gardée ; --resume reprend une mise à jour interrompue.
Pour retirer, lisez uninstall --dry-run puis lancez uninstall ou uninstall --keep-state pour garder le manifeste d’installation actif et marqué retiré. Le registre est toujours conservé ; sans cette option, le manifeste terminé est archivé avec les sauvegardes. Les sauvegardes restent disponibles au chemin affiché ; les dépendances séparées ne sont pas retirées. Un retrait interrompu reprend par uninstall --resume. Corrigez d’abord la cause signalée, ne supprimez pas le journal.
lab update --catalogue
lab update --rollback
lab uninstall --dry-run
Données et réseau
Treelab n’envoie aucune télémétrie. Trois moments seulement parlent au réseau : l’installeur (achat, puis activation de la licence avec votre clé et un identifiant aléatoire de ce Mac, machine_id), lab update et la mise à jour automatique de lab next (votre licence et ce même identifiant, pour télécharger la version). Le reste, dont vos dépôts et vos fiches, reste sur votre poste et dans vos propres dépôts distants.
Le site ne charge aucun service de diagnostic et ne demande jamais votre clé. Le package, ses messages et l’assistant d’installation sont en anglais, et l’agent vous répond dans la langue de votre Mac ; ce guide et le site existent en français et en anglais.
Référence des commandes
Les crochets indiquent une option, les chevrons un élément à remplacer, et | un choix. Ce sont des syntaxes de référence, pas des lignes à coller telles quelles. projet est facultatif quand le dossier courant identifie le dépôt enregistré. Les noms et options restent ceux du package français.
L’installeur la lance pour vous après l’achat ou la saisie de la clé ; vous pouvez la relancer à tout moment. Elle vérifie le poste, résume ce qui sera installé, puis attend que vous tapiez I accept avant d’écrire. --dry-run montre le plan sans rien installer. --reapply réapplique les choix mémorisés. --import reprend une installation antérieure : liens, hooks, registre, fiches et préférences. --dev sert au checkout de développement de Treelab.
Pose instructions, skills, agents, hooks et commandes, et propose cmux séparément s’il manque ; vos réglages existants sont conservés et sauvegardés. Aucune session d’agent ne doit tourner pendant l’opération. Si le plan change, relancez et relisez-le. Après l’installeur, votre premier couloir est déjà ouvert ; lancée seule, elle conseille lab doctor, puis lab onboard dans le dossier d’un projet.
doctor · Diagnostiquer
lab doctor [project] [--root <checkout|worktree>] [--project-only] [--report|--freeze] [--json]
Sans projet, contrôle l’installation du poste ; avec un projet, son cadre de travail. Chaque point est vert, en avertissement ou rouge, et un rouge dit quoi corriger. --root choisit le checkout ou le worktree ; --project-only omet les contrôles globaux. Le bilan normal peut afficher des chemins privés : gardez-le sur votre poste.
--report produit un rapport anonymisé, sans écriture ni envoi ; --json structure la sortie. Code 0 : aucun rouge ; 1 : contrôle rouge ; 2 : options ou diagnostic invalides. --freeze recale la référence des mesures du projet, seulement pour un changement voulu et noté au journal, jamais pour cacher un rouge. LAB_DOCTOR_SKILLS_WARN_LIMIT fixe un seuil facultatif, avertissement seulement.
Télécharge la dernière version avec votre licence, vérifie l’archive et son empreinte, puis bascule dessus. Les sessions d’agent ouvertes gardent leur version ; la suivante part de la nouvelle. --catalogue lit seulement la version disponible. --rollback revient, sans réseau, à la version précédente conservée ; --resume reprend une mise à jour interrompue. --adopt, lancé depuis une release extraite, remplace une pose antérieure.
Sans rien taper, lab next pose la dernière version mineure ou corrective une fois par jour au plus ; une version majeure est seulement annoncée. Pour ne recevoir que l’annonce, écrivez auto_update=no dans ~/.lab/config. Tout échec finit par RESULT=refused ou interrupted, avec REASON= et le fichier en cause : la version en place est conservée.
Hors session vivante, lisez d’abord --dry-run. Le retrait réel exige l’accord au terminal. --keep-state garde le manifeste d’installation actif et marqué retiré ; --resume reprend le retrait interrompu après correction de sa cause.
Retire seulement les éléments attribués au manifeste, restaure les réglages sauvegardés et conserve les changements tiers. Sauvegardes conservées dans le chemin affiché, dépendances installées séparément conservées. Le registre est toujours conservé. Sans --keep-state, seul le manifeste terminé est archivé avec les sauvegardes. Si le journal ou une empreinte ne correspond plus, conservez les fichiers et rétablissez leur intégrité avant la reprise.
onboard · Visite guidée
lab onboard [--agent claude|codex]
À lancer dans le dossier de votre dépôt Git. Trois écrans présentent les mots, le cycle et les garanties. Le dépôt est ensuite enregistré comme projet, sans toucher à vos fichiers, la tour du projet s’ouvre dans son onglet « tower », et un agent s’ouvre dans l’onglet « main » du projet : il vous demande votre besoin et ouvre votre premier couloir.
Relancer la commande ne crée rien en double. --agent choisit Claude Code ou Codex. Sans cmux, elle affiche la commande à lancer vous-même (NEXT_COMMAND).
lab onboard le fait pour vous la première fois. Depuis un dépôt Git existant, name nomme le projet et --root choisit sa racine. --docs repo place les futurs documents dans les worktrees ; local les garde hors dépôt. --owner shared|other décrit la propriété, sans autoriser une écriture dans le checkout principal. --agent fixe l’agent par défaut.
Écrit le registre local, détecte base, distant et commandes du projet ; tente un fetch. Le checkout principal reste intact. PROJECT et ROOT identifient le dépôt enregistré. Si le dépôt est indéterminé, précisez --root vers sa racine Git.
Depuis le dépôt enregistré, choisissez un nom court de couloir. --brief range le texte de votre besoin avec les documents du couloir : l’agent part de lui. --batch nomme le premier lot, --kind le type de branche, --base sa base, --title son titre et --agent son agent. --no-open omet l’onglet ; --no-install omet l’installation des dépendances du projet ; --permanent crée le couloir déjà permanent.
Crée .worktrees/<lane>, sa branche, ses métadonnées et la fiche du premier lot ; installe normalement les dépendances puis ouvre l’onglet cmux avec l’agent, qui commence par quelques questions de cadrage. WORKTREE, BRANCH et LOT permettent de retrouver le résultat. Le dépôt principal doit être sans changement en attente. Si le couloir existe déjà, utilisez open.
next · Passer à l’étape suivante
lab next [project] <lane> [--agent claude|codex] [--goal <criteria>] [--auto] [--local]
lab next [project] <lane> --batch <slug> [--kind feat|fix|chore] [--title <text>]
Lit où en est le couloir et lance ce qu’il faut : exécuter ou reprendre le lot, ouvrir le lot suivant après une livraison, ou préparer votre essai final. --goal complète l’objectif ; --agent choisit l’agent. Lancée depuis la session du couloir, elle la remplace par une session neuve dans le même onglet ; --auto reste accepté comme synonyme. Avec cmux et le Cloud réglé à yes, l’exécution du lot part sur une machine Cloud (CLOUD_RUN=) puis revient au Mac pour la clôture, sauf si sa fiche demande le Mac (ligne Execution, lab deploy ou lab lock dans ses étapes) ; le choix est annoncé en une ligne (EXECUTION=) et --local garde toujours le Mac.
La seconde forme impose le lot suivant, par exemple une correction après votre essai (--kind fix). Une dernière nuit rouge de la branche principale est annoncée (NIGHT=) avec un couloir de correction proposé (NIGHT_FIX=), sans rien bloquer. next ne fusionne ni ne supprime rien. Une autre session vivante ou une livraison manquante impose de terminer l’étape indiquée avant de relancer.
permanent · Garder un couloir ouvert pour de bon
lab permanent [project] <lane> [on|off]
Sans valeur, ou avec on, le couloir devient permanent : il enchaîne ses lots, chacun livré par sa propre pull request. off le rend ordinaire. lab new … --permanent le crée déjà permanent.
Un couloir permanent n’est jamais proposé à l’essai (recette), au retrait ni à la fermeture : lab close et lab close --abandon le refusent et nomment le remède. Quand aucun lot ne reste, lab next ouvre une session libre qui attend votre demande. PERMANENT=yes ou no donne le résultat ; lab status, lab list, lab plan et lab sweep affichent PERMANENT=yes.
Chaque projet a sa tour : lab onboard la crée pour un nouveau projet. Le premier appel crée la tour : le couloir permanent tower, lancé sous Claude en mode bypassPermissions (le premier lancement peut vous demander une fois de confirmer ce mode). Sa session applique la skill tower : toutes les 30 minutes environ, elle passe chaque couloir en revue, relance celui qui s’est arrêté, livre ce qui est prêt et liste ce qui attend de vous. Elle ne répond jamais à votre place. Une tour sous Codex est refusée.
Les appels suivants affichent TOWER=present, puis un bloc par couloir : LANE=, WAITS_FOR= (you, acceptance, date, ci ou nothing), WHY= et SESSION=. Dans tous les projets, avec ou sans tour, une question, une autorisation demandée, une recette prête ou un lab next refusé envoie une alerte cmux vers l’onglet du couloir. --all propose une tour à chaque projet inscrit qui n’en a pas : une question [y/N] par projet dans un terminal, rien créé sans terminal (CONFIRM=needed) ; --no-install saute l’installation des dépendances. lab wake relance dans l’heure une tour sans session, et lab doctor montre la tour de chaque projet, pour information.
plan · Voir la progression
lab plan [project] [--json]
Recalcule à chaque affichage, depuis les fiches : le lot courant de chaque couloir, les lots faits sur le total et la phase.
Lecture seule. Tableau lisible sur stderr, champs ou JSON sur stdout. Si le plan est vide, créez le premier couloir avec new.
status · Lire l’état détaillé
lab status [project]
Le projet (dossier, branche, cible des fusions, agent par défaut), puis chaque couloir comme list, les livraisons en attente, ce qui est en ligne et les fichiers touchés par deux couloirs à la fois.
Lecture seule ; un verrou dont le processus est mort peut être purgé à la lecture. Si le projet est indéterminé, précisez le nom enregistré.
list · Inventorier les couloirs
lab list [project]
Un bloc par couloir : dossier, branche, lot et état, agent, demande de fusion, session en cours. Sans projet : tous les projets enregistrés.
Lecture seule. Si un projet manque, vérifiez init depuis sa racine, sans recréer ses fichiers de travail.
top · Voir qui occupe le poste et couper au clic
lab top [--fast]
lab top --cut <pid|family|idle|lane-done>
lab top --wake <tab>
lab top --explain <pid|family>
Sans option, une photographie en lecture seule : pression mémoire, mémoire compressée, débordement, charge et état thermique ; chaque session claude ou codex rattachée à son projet, à son couloir et à son onglet cmux ; les familles hors Treelab (Chrome, navigateurs de test, machines virtuelles, node, cmux) ; enfin ce qui peut être coupé, chaque fois avec son motif, ce que la coupure implique et la commande du clic. Les sessions endormies par lab sont listées avec leur commande de réveil.
Un geste à la fois, sans confirmation : lab revérifie le motif au moment d’agir et refuse sinon, en nommant le refus. --cut endort une session inactive dans son onglet (réveil sur place par --wake), ferme l’onglet d’un couloir fini après vérification du Handoff, des fichiers non commités et de l’inactivité, arrête un processus hors agent (signal d’arrêt, 10 secondes, puis arrêt forcé ; une famille par sa racine, une VM Lima par limactl stop) ; --cut idle et --cut lane-done traitent tout un motif. Un agent n’est jamais tué, ni une session à l’écran ou qui fait tourner une commande de fond ; cmux, la session appelante, les parents des sessions, les processus root et les noms de top_keep= ne sont jamais proposés. --explain ouvre un onglet où Claude, en mode plan, explique avant toute coupure.
sysmon · Mesurer le poste pour les modules de la barre
lab sysmon
Une seule passe de collecte rend six blocs : processeur, mémoire, disques, réseau, batterie et températures. macmon (posé par brew) donne l’usage des cœurs performance et efficience, le GPU, la puissance, les températures et les ventilateurs ; les outils natifs donnent la mémoire, les disques, le débit réseau et la batterie. Chaque bloc porte ses chiffres et, pour le processeur et la mémoire, les cinq plus gros consommateurs rattachés à leur projet et à leur couloir pour les sessions d’agent.
Sans macmon, les températures et la puissance disparaissent, les autres modules restent entiers. Un seul collecteur alimente les six modules de la barre (lab widget) : chaque greffon ne fait que lire son cache, jamais relancer macmon. Blocs KEY=value sur stdout, vue lisible sur stderr ; --fast reste accepté. Lecture seule, rien n’est coupé.
mcp · Voir les serveurs d’outils
lab mcp
lab mcp --pin|--bump|--undo [--yes]
Liste chaque serveur d’outils (MCP) configuré pour Claude et Codex, en global et dans chaque projet enregistré : portée, transport, paquet et version figée ou non (@latest ou sans version : non figée, chaque lancement peut en tirer une nouvelle). Puis les copies vivantes regroupées par paquet : copies, processus et mémoire résidente ; les sessions d’agent ne sont jamais comptées.
Aucun secret n’est jamais affiché : ni variables d’environnement, ni en-têtes, ni adresses, ni autre argument que le nom du paquet. lab doctor avertit au-delà de 1024 Mo (mcp_rss_warn_mb= dans la configuration de lab) ou pour une version non figée. Blocs KEY=value sur stdout, vue lisible sur stderr. Sans option, lecture seule. --pin fige chaque serveur lancé par npx sur la version qu’il lance (lue dans le cache de npx, sans réseau) ; --bump propose la dernière version publiée sur npm ; chacun montre le changement (paquet avant → après, jamais le contenu d’un fichier) et demande l’accord, puis sauvegarde chaque fichier avant de l’écrire ; --undo restaure la dernière sauvegarde. Un serveur lancé autrement (uvx, pipx) est nommé avec sa raison, jamais figé.
install pose la pastille lab top (toutes les 60 s : couleur selon la pression mémoire, sessions d’agent, coupures proposées ; son menu coupe au clic) et six modules système (processeur, mémoire, disques, réseau, batterie, températures) rafraîchis toutes les 10 s, chacun un élément de barre avec son menu détaillé. lab pose macmon par brew pour les températures et la puissance ; sans lui, les modules natifs restent. modules list montre les modules actifs, off en retire un, on le remet.
SwiftBar n’est jamais installé par lab : sans lui, install affiche brew reinstall --cask swiftbar et s’arrête. Les greffons vont dans le dossier que SwiftBar utilise déjà, sinon dans un dossier de lab inscrit dans ses préférences ; SwiftBar s’ouvre à la connexion. Un seul collecteur alimente les six modules (lab sysmon), le budget le veut. remove retire la pastille et les six modules, et l’ouverture à la connexion si lab l’a posée ; macmon, les préférences et les autres greffons restent. Un chevron, posé à gauche de la pastille, range la barre : replié, il pousse hors de l’écran toutes les icônes à sa gauche ; son menu dessine la carte de la barre, signale une icône lab cachée, une app neuve, un ordre qui a bougé, et guide le rangement en quatre étapes. order save garde l’ordre, order apply le rétablit (une app lancée ne se relance qu’avec --relaunch, jamais cmux, les agents ni SwiftBar), et refuse si Bartender, Ice ou Hidden Bar tourne ; tidy resserre l’espacement, masque les doublons du Centre de contrôle et coupe iStat Menus, chaque geste annoncé puis défait par remove.
Après le dernier lot, vous essayez le résultat ; l’agent note votre décision en une commande. La révision essayée est relevée, la section « Lane acceptance » de la dernière fiche (« Recette du couloir » dans une fiche française) est écrite, puis enregistrée seule. Un accord exige au moins une --evidence ; un refus peut porter vos --feedback.
Refus si le couloir n’est pas en recette ou si des changements ne sont pas enregistrés. ACCEPTANCE=valid ou rejected, REVISION= et COMMIT= identifient la décision. Si le résultat change ensuite, la recette est à refaire avant close.
close · Livrer puis retirer le couloir
lab close [project] <lane> [--confirm <lane>] [--retire <sha>…] [--night-red-ok <reason>]
lab close [project] <lane> --abandon [--confirm <lane>]
lab close [project] <lane> --dry-run [--abandon]
Présente ce qui sera livré et retiré, puis demande de retaper le nom du couloir ; --confirm le fournit après un accord déjà donné. Elle exige votre essai et votre accord, notés par acceptance. Elle fusionne ensuite le dernier lot, retire la copie de travail, les branches et l’onglet. --dry-run liste d’un coup tous les obstacles (OBSTACLE=, puis RESULT=ok ou blocked) sans rien modifier.
Juste avant la fusion, la branche principale est relue à jour : si la fusion retirait des lignes ajoutées par un autre couloir, close refuse et les nomme ; --retire <sha> confirme ce retrait. Si la dernière nuit de la branche principale est rouge, close refuse et propose un couloir de correction ; --night-red-ok "<motif>" passe outre en écrivant un accord daté dans la section de recette de la fiche. --abandon retire un couloir qui n’a rien à livrer, après la même confirmation. Des fichiers non enregistrés, une session vivante ou une recette périmée bloquent : la confirmation ne contourne jamais un rouge.
sweep · Inventorier les attentes
lab sweep [project] [--dry-run]
Pour chaque couloir : sa branche, si elle est fusionnée, et ce qu’il attend (un essai, une fermeture, la suite du lot).
C’est un inventaire : il ne supprime rien, ne fait ni fetch ni prune. Seul close retire un couloir.
open · Retrouver l’onglet
lab open [project] <lane> [--agent claude|codex] [--prompt <text>|-]
Commande de secours : retrouve l’onglet du couloir, ou le rouvre avec son agent, sans décider d’une nouvelle étape. --prompt donne un texte, et - le lit sur l’entrée standard.
Pour avancer, utilisez next. Si cmux est introuvable, ouvrez l’application avant de réessayer. Ne lancez pas une seconde session si la première travaille encore.
Vous n’avez pas à la taper : new et next l’écrivent dans l’onglet du couloir. Elle relit la fiche du lot, reconstruit la consigne complète de l’agent (le Goal) et lui laisse la place.
Une ligne courte part dans l’onglet et le Goal est reconstruit à l’arrivée, sans troncature. Le lancement automatique appelle le nom court lab : si un autre outil occupe ce nom, utilisez treelab pour vos appels directs et contactez le support. Un long complément s’écrit dans la fiche, pas dans --goal.
Fusionne la demande de fusion du lot vers staging si elle existe, sinon vers la branche principale, dès que les contrôles automatiques sont verts. S’ils tournent encore, un veilleur fusionnera après le vert et la commande rend la main (ACTION=armed). --title et --body-file fixent le titre et le corps de la demande. L’agent la lance à la fin de chaque lot.
Avant de fusionner, la commande puis le veilleur refont un essai à blanc sur la base fraîche et refusent une fusion qui retirerait des lignes ajoutées par un autre couloir (REGRESSION=) : le refus nomme fichier, lignes et commit ; --retire <sha> autorise ce retrait voulu. gh et les droits du dépôt distant sont nécessaires.
sync · Ramener la base dans un couloir
lab sync [project] <lane>
Fusionne dans le couloir les changements arrivés sur la branche de base, sans rien pousser. launch le fait avant chaque session.
SYNC=up-to-date, merged, conflict ou ignored. Un conflit est annulé et nommé (CONFLICT_FILES=) : le couloir reste intact jusqu’à sa résolution.
promote · Mener staging en production
lab promote [project] [--confirm <project>]
Sans --confirm : présente ce qui partirait de staging vers la branche principale, sans rien écrire. Avec --confirm : ouvre la demande de fusion datée et la fusionne à la révision exacte après des contrôles verts.
À lancer vous-même ; un agent ne la lance que sur votre demande explicite. PROMOTE=preview, armed, merged ou none ; PR=, INCLUDED= et INFLIGHT= détaillent le contenu.
batch · Lire les fiches de lot
lab batch current
lab batch list
lab batch new [--title <text>]
lab batch processes
lab batch wait <Cn> <YYYY-MM-DD|YYYY-MM-DDTHH:MM:SSZ|+Nd> "<reason>"
lab batch wait --done <Cn>
À lancer dans le dossier d’un couloir. current donne la fiche du lot en cours et son état ; list donne chaque fiche et son état ; new crée la fiche d’un lot, --title fixe son titre ; processes nomme ce qui tourne encore dans le dossier du couloir, hors la session qui demande : rien n’est arrêté, l’agent arrête chacun ou le justifie dans la fiche. wait met un critère en attente d’une mesure datée : la fiche passe « en attente », le lot est livré comme les autres et le couloir continue.
Les agents s’en servent pendant un lot. new ne remplace pas next pour changer de branche et de session ; ne créez pas une fiche concurrente pour contourner un lot actif. À la date, lab next rouvre la fiche pour ce seul critère, avant le lot suivant ; un seul report par critère ; wait --done le marque mesuré. Recette et fermeture attendent que chaque attente du couloir soit mesurée.
handoff · Vérifier le passage de relais
lab handoff [project] [lane] [--template]
Vérifie que la fiche du lot dit où en est le travail et quel lot suit, enregistre les fiches du couloir, puis imprime la commande suivante (NEXT_COMMAND). Si la section Reprise manque, ajoute son gabarit à la fiche et demande de la remplir. --template affiche seulement la forme attendue.
L’agent la lance en fin de lot. Elle ne livre pas le lot et ne vérifie pas la complétude des preuves : objectif, lectures, preuves, reste et prochain lot restent à écrire.
wake · Rouvrir les lots en attente à leur date
lab wake
lab wake --install
lab wake --remove
lab wake --status
Sans option : pour chaque couloir des projets inscrits dont une mesure attendue est due, sans session vivante, lance lab next, qui rouvre la fiche pour ce critère ; la tour d’un projet sans session vivante est relancée de la même façon. --install pose l’alarme macOS : un agent de lancement qui appelle lab wake toutes les heures et à l’ouverture de session ; lab batch wait la pose aussi.
Chaque passage est écrit dans wake.log du dossier d’état, avec CMUX=reachable ou absent. --status dit si l’alarme est chargée et son dernier passage ; --remove la retire. Un Mac éteint à la date rattrape au réveil ; sans alarme, ou si cmux refuse les processus qu’il n’a pas lancés, le prochain lab next rouvre la fiche (PENDING=).
now · Horodater
lab now
Imprime l’instant présent en temps universel, au format AAAA-MM-JJTHH:MM:SSZ. Les agents s’en servent pour dater journaux et Reprises.
LAB_NOW fixe la valeur, pour les essais.
due · Suivre les échéances
lab due [project]
lab due [project] add <YYYY-MM-DD|YYYY-MM-DDTHH:MM:SSZ> <subject…>
lab due [project] done <id> <sha>
lab due [project] reschedule <id> <due date>
lab due [project] cancel <id> <reason…>
Sans action : les échéances ouvertes du projet, en retard d’abord, puis celles sous 48 heures, puis les suivantes. add inscrit une échéance prise pendant un lot (relance, livraison promise).
fait tranche une échéance avec le commit qui la prouve ; redater la déplace ; annuler la ferme avec un motif. Les échéances ne vivent ni dans les fiches ni dans la Reprise.
Le compte n° 1 est celui de votre /login. add guide trois étapes : votre /login devient le badge du compte, claude setup-token donne le jeton rangé dans le trousseau macOS (jamais dans un fichier), puis ce jeton rejoint CodeRouter, les comptes d’équipe qu’empruntent les machines Cloud ; une étape ratée garde les précédentes. coderouter envoie plus tard à CodeRouter un jeton déjà rangé ; une étiquette déjà présente dans l’équipe n’est jamais remplacée. remove l’efface ; sans action, la liste dit quel compte est disponible.
Quand un compte atteint sa limite de 5 heures ou de 7 jours, la même conversation reprend dans son onglet sur le compte suivant ; si tous sont épuisés, l’onglet attend l’heure de reprise. suivant change de compte tout de suite, depuis la session Claude du couloir. resume relance un par un, espacés de 25 s (LAB_RESUME_GAP), les onglets en attente et les sessions de couloir arrêtées par la limite ou un 401, après un vrai appel qui vérifie chaque jeton ; add et free le font seuls, --dry-run montre seulement ce qui serait relancé. badge range la connexion du /login actuel comme badge du compte relié à son e-mail ; use, et la rotation à la limite, posent ce badge pour tout le Mac (extension Chrome, pages, dictée sans /login), après avoir resauvé le badge actif. Un /login tapé dans une session est adopté comme badge de son compte. À la limite, l’onglet main et un claude tapé à la main sont relancés dans leur onglet cmux par run, avec leurs options ; hors cmux, le badge du compte suivant est posé et le journal dit quoi taper. reserve on marque un compte de dernier recours : pris seulement quand aucun autre ne peut servir, quitté au lancement suivant dès qu’un autre est libre ; add --last-resort en ajoute un sans l’envoyer à CodeRouter.
Sans valeur, affiche la règle appliquée et d’où elle vient : CLOUD= et CLOUD_SOURCE= (couloir, projet, réglage du poste ou défaut). Le couloir l’emporte sur le projet, le projet sur cloud= de ~/.lab/config, et la valeur par défaut est yes. no garde tous les lots sur le Mac ; avec yes, chaque fiche choisit, sans question.
yes ou no écrit la règle au projet, ou au couloir s’il est nommé ou si la commande est lancée dans son dossier ; reset retire la règle de ce niveau. Une valeur illisible est refusée avec la commande qui la corrige ; ~/.lab/config est lu, jamais écrit. image prépare une fois la machine du projet et la fige. Chaque lot Cloud reçoit, sans geste, une clé de déploiement du dépôt créée par gh : la paire est générée sur la VM, seule la clé publique remonte, la VM clone et pousse en SSH, et la clé est révoquée sur GitHub à la fin, même VM en pause. Une session Cloud bloquée sur un besoin du Mac (« blocked: need <besoin>: <détail> ») revient seule sur le Mac et ce besoin est retenu hors du dépôt : needs les liste, needs reset les oublie ; sans valeur, lab cloud montre aussi les besoins (NEED=) et les 5 dernières sessions Cloud (SESSION=). suite joue la suite bats du commit courant sur une machine Cloud jetable à la taille du forfait (une tâche bats par vCPU, image périmée refaite d’abord), supprimée ensuite même en échec : SUITE=green, red ou unavailable, en code retour 0, 1 ou 3, sans jeton. Forfait encore plein après le ménage : la même suite part aussitôt sur le Mac (RUN=mac), avec l’alerte qu’un forfait plus grand la garderait sur le Cloud. clean libère le forfait : VM du projet que plus rien n’utilise et snapshots plus anciens que le précédent, jamais l’image, un couloir ouvert ni une machine d’un autre projet ; --dry-run les nomme seulement. Le même ménage passe avant chaque suite et chaque départ de lot Cloud.
add copie les captures, sorties et mesures d’un lot hors du dépôt, avec l’empreinte SHA-256 de chaque fichier dans un manifest.json ; un fichier déjà versionné est seulement référencé. --step range la preuve sous une étape nommée.
verify recalcule chaque empreinte et signale une preuve modifiée ou absente.
lock · Tenir une ressource partagée
lab lock [project] <resource> [--pid <pid>]
Réserve pour le couloir courant une ressource déclarée dans la configuration du projet (resources=) : un simulateur, une base locale, un port. --pid désigne le processus détenteur.
Si un autre couloir vivant la tient, la commande refuse et le nomme ; un détenteur mort est remplacé. unlock la libère.
unlock · Libérer une ressource
lab unlock [project] <resource>
Libère une ressource tenue par le couloir courant, ou par une session qui n’existe plus.
Une ressource tenue par un autre couloir vivant reste à lui.
served · Noter la version servie
lab served <port> [--pid <pid>]
Appelée par le script de développement du projet : elle note le couloir, sa révision, le port et le processus qui sert l’application.
Au démarrage d’une session, l’agent sait ainsi quelle version tourne localement.
Lance le crochet du projet, un seul fichier exécutable versionné avec le code : scripts/lab-services. lab le reconnaît à sa seule présence et l’appelle avec le verbe stop, depuis le dossier du couloir — la pile Docker, la base ou les conteneurs de ce couloir sont arrêtés et retirés.
close et close --abandon le lancent eux-mêmes juste avant de retirer le dossier ; cette commande le relance après coup, par exemple après un premier échec. Le crochet reçoit LAB_PROJECT, LAB_LANE et LAB_WORKTREE (vide quand le dossier a déjà disparu : c’est alors la copie du checkout principal qui sert, nommée car elle peut être plus ancienne). Il a 120 secondes ; au-delà, lui et ses enfants sont arrêtés. Un échec ne bloque jamais une fermeture : lab le nomme et retire le couloir quand même. Avec le verbe list, le crochet nomme ce que les couloirs gardent encore, une ressource par ligne : list les montre couloir par couloir, lab sweep et lab doctor nomment ceux d’un couloir déjà fermé (15 secondes au plus, sans jamais rien arrêter), et stop --orphans les arrête tous, un couloir après l’autre. Exemple prêt à copier pour une pile Compose nommée d’après le couloir : templates/project/lab-services.
deploy · Mettre en ligne sans effacer un autre couloir
Met en ligne une cible déclarée dans la configuration du projet, toujours depuis la branche principale à jour ; depuis un couloir, sa branche s’y ajoute, et --with en ajoute d’autres. --dry-run montre le plan et ce qui serait perdu (LOST=). --record inscrit l’existant sans déployer. --add déclare une cible depuis un modèle worker, rsync ou cloudrun ; --include nomme les fichiers privés copiés avant chaque mise en ligne.
Un registre note ce qui est servi. Si la cible sert un couloir non fusionné que vous n’incluez pas, lab refuse et le nomme : incluez-le avec --with, ou retirez-le avec --retire. La sonde vérifie ensuite la révision servie. Dans un projet qui déclare une cible, un déploiement direct est refusé : passez par lab deploy.
watch · Le veilleur d’une livraison
lab watch <project> <lane> <branch>
Commande interne : vous n’avez pas à la lancer. merge et close la démarrent en arrière-plan pour attendre les contrôles automatiques, puis fusionner.
Commande interne : Claude Code et Codex l’appellent avec du JSON sur l’entrée standard, au début et à la fin d’une session, et avant une commande risquée. session-start fournit le contexte et le verrou ; session-end libère la session ; notify note une question ou une autorisation et alerte l’onglet du couloir ; guard-bash et guard-tool refusent par défaut les gestes dangereux courants, avec l’alternative sûre.
Une erreur interne d’un automatisme ne bloque jamais votre travail. Codex demande une approbation unique des hooks (/hooks) ; doctor vérifie qu’ils sont en place.
help affiche, en anglais, les commandes rangées par moment (install, start, move forward, finish) ; help <command> donne à quoi elle sert, sa syntaxe et un exemple ; help glossary donne chaque mot anglais de lab avec son ancien mot français. --help et -h affichent la référence technique complète sur stderr et sortent à 2. --version produit VERSION=… depuis la copie exécutée.
--json transforme les sorties KEY=value de toute commande en JSON ; les explications restent sur stderr. Un code non nul se lit dans le contexte de la commande ; doctor distingue 1 et 2.
Dépannage
Outil absent
Vérification et action
Relancez la commande d’installation : elle propose d’installer Git et jq via Homebrew ; lab setup propose cmux. Vérifiez aussi macOS et command -v pour votre agent.
Résultat attendu
Chaque outil affiche un chemin ; l’installation reprend sans nouvel achat.
Clé non reçue
Vérification et action
Attendez quelques minutes et vérifiez les indésirables. Un achat avec fourniture différée reçoit sa clé à la fin du délai de rétractation. Ensuite, relancez la commande d’installation et choisissez 2 « Enter a key » (saisir une clé), ou écrivez au support depuis l’adresse du paiement.
Résultat attendu
La clé tl_key_ est collée et activée ; aucun second paiement.
lab occupé
Vérification et action
Comparez command -v lab et command -v treelab. Utilisez treelab sans remplacer la commande tierce.
Résultat attendu
treelab --version identifie la bonne copie pour les appels directs. Le lancement automatique appelle encore lab : s’il est occupé, conservez l’autre outil et contactez le support.
Dépôt non enregistré
Vérification et action
Depuis la racine Git voulue, vérifiez lab list puis relancez lab onboard, ou lab init avec --root.
Résultat attendu
PROJECT et ROOT correspondent au dépôt voulu.
Onglet introuvable
Vérification et action
Vérifiez lab status, ouvrez cmux puis lab open avec le nom du couloir existant.
Résultat attendu
L’onglet du couloir est retrouvé ou recréé.
Session encore vivante
Vérification et action
Revenez à l’onglet propriétaire et terminez proprement la session. Pour une reprise automatique par son agent, enregistrez d’abord la Reprise puis lancez lab next depuis cette session.
Résultat attendu
Une seule session travaille ; entretien possible après sa fin. Ne supprimez pas son verrou.
Bilan rouge
Vérification et action
Lisez NOTE dans doctor local et corrigez le contrôle indiqué ; relancez exactement le même bilan. --freeze ne sert pas à cacher le défaut.
Résultat attendu
Le contrôle concerné devient vert, sans déplacement artificiel de la référence.
Livraison bloquée
Vérification et action
Vérifiez cible de la demande de fusion, contrôles distants, conflit, droits gh et recette du dernier lot ; lab close --dry-run liste les obstacles. Corrigez la cause avant de relancer ; gardez le couloir.
Résultat attendu
Contrôles et bilan verts, puis demande réellement fusionnée.
Mise à jour refusée
Vérification et action
Lisez RESULT, REASON et FILE affichés par update. Vérifiez la connexion et la licence de ce Mac, puis réessayez ; --resume reprend une mise à jour interrompue.
Résultat attendu
Aucun remplacement sur échec ; mise à jour seulement après archive vérifiée.
Version précédente absente
Vérification et action
Lisez le refus de update --rollback ; conservez la version actuelle et les sauvegardes. Ne fabriquez pas previous-release.
Résultat attendu
Installation conservée ; demande de support possible avec rapport relu.
Opération interrompue
Vérification et action
Corrigez les droits ou l’intégrité indiqués, gardez les sauvegardes, puis utilisez update --resume pour la mise à jour ou uninstall --resume pour le retrait demandé par le diagnostic.
Résultat attendu
Transaction terminée ou restaurée ; vérifiez doctor avant de reprendre le travail.
Dans votre terminal, lancez lab doctor --report. Relisez stdout et stderr avant tout partage : ce mode anonymise le diagnostic existant, pas les commentaires que vous ajoutez. Le bilan normal sans --report peut contenir des chemins privés. Ne le joignez pas tel quel.
lab doctor --report
Variante facultative depuis un dossier local privé : choisissez un nom de fichier nouveau, car > remplace un fichier existant. Le code 1 signifie un bilan rouge, pas un échec d’anonymisation ; le code 2 indique une erreur à résoudre avant de partager. Le fichier reçoit stdout JSON ; stderr reste au terminal et doit aussi être relu.
lab doctor --report --json > treelab-report.json
Vérifiez l’absence de noms, chemins personnels, adresses, clés et contenus de projet. Retirez toute information inutile, puis ajoutez manuellement le rapport si vous le souhaitez. Le site ne lit, ne reçoit ni ne conserve ce fichier. Le lien d’e-mail ne contient aucun diagnostic ; seule votre messagerie pourra envoyer après votre action.