De votre dépôt Git au premier couloir, puis les commandes pour continuer et retrouver votre chemin.
Le texte reste sélectionnable. Vérifiez les chemins avant de coller une commande dans votre terminal.
Préparer le poste
Il vous faut macOS 13 ou supérieur, Git, jq, cmux et au moins une commande d’agent disponible. Ce guide utilise Codex, avec un accès déjà configuré dans votre terminal. Sur un compte vierge, sa connexion et l’approbation des hooks restent à effectuer avant le travail de l’agent. Les comptes, accès et abonnements tiers sont séparés. gh et ses droits GitHub seront nécessaires pour livrer une PR, pas pour lire le guide.
Dans un terminal visible, vérifiez le système et les commandes ci-dessous. Chaque command -v doit afficher un chemin ; une absence demande d’installer ou de rendre l’outil accessible dans PATH puis de refaire la vérification. Ouvrez cmux avant la création du couloir. Le setup peut préparer cmux via Homebrew si ce dernier est présent, après accord séparé.
sw_vers -productVersion
git --version
jq --version
command -v cmux
command -v codex
Installer depuis une copie locale
Le parcours disponible commence avec une copie locale complète dont vous avez vérifié l’origine. Le téléchargement privé après achat et l’activation distante restent à venir. Ne lancez pas de bootstrap distant annoncé mais non vérifié. Le package, ses messages et les réponses de consentement restent en français.
Depuis la racine de cette copie, vérifiez la version. Une distribution préparée possède .release et le lien current vers cette copie : utilisez ./bin/lab setup --dry-run puis ./bin/lab setup. Si vous utilisez un checkout de développement, les deux commandes ci-dessous utilisent --dev. Ne créez pas .release pour transformer un checkout en distribution.
Terminez les sessions d’agents avant l’installation. Le plan indique instructions, skills, hooks, commandes, profil shell et sauvegardes concernés. Lisez-le avant de lancer la commande réelle ; saisissez j’accepte seulement si vous acceptez ces changements. RESULT=simulated signifie simulation ; RESULT=installed confirme la pose. En cas de refus ou de plan changé, rien n’est installé : relisez puis relancez.
./bin/lab --version
./bin/lab setup --dev --dry-run
./bin/lab setup --dev
Vérifier la commande installée
Ouvrez un nouveau terminal pour prendre en compte PATH. La commande distribuée s’appelle treelab ; lab est son nom court quand ce nom est libre. Si lab désigne un autre outil, conservez-le et utilisez treelab pour les appels directs. Limite du package 0.1.0 : les nouveaux onglets exécutent encore lab launch. Le démarrage automatique de ce guide suppose donc que lab désigne Treelab dans ces onglets. Si ce nom est occupé, gardez l’autre outil et demandez de l’aide avant de poursuivre cette étape.
La version doit correspondre à la copie vérifiée (VERSION=0.1.0 pour la révision documentée). doctor explique ses contrôles par NOTE : corrigez chaque rouge et approuvez les hooks dans les agents si demandé, puis relancez. Le contrôle d’une licence locale ne prouve pas son activation distante. Le bilan normal peut contenir des informations privées : gardez-le sur votre poste.
treelab --version
treelab doctor
command -v lab
Créer 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é.
Dans les exemples, remplacez /chemin/vers/depot par la racine d’un dépôt Git existant avec un premier commit, demo par le nom choisi pour son enregistrement, et premier par le nom du besoin. Le checkout principal doit être propre. init enregistre localement le dépôt ; il n’y ajoute pas de documents. --docs repo les placera dans le futur couloir. Un avertissement de fetch hors ligne est distinct d’un échec d’enregistrement : vérifiez PROJECT et ROOT.
new crée .worktrees/premier, une branche et docs/lots/premier/lot-01-premier.md, puis ouvre l’onglet cmux. Il peut installer les dépendances du dépôt. L’agent commence par qualifier le besoin, rédiger le plan et la fiche ; cette ouverture ne prouve pas un lot exécuté. Repérez la question de cadrage et répondez dans cet onglet.
Si le dossier existe mais que l’onglet manque, utilisez lab open demo premier après vérification de la session. Ne relancez pas new pour recréer un couloir existant. Après la planification et la fermeture de cette session, lab next demo premier ouvre l’exécution avec le Goal de la fiche.
Dans l’onglet du couloir : qualifier → planifier → exécuter → vérifier → livrer. Les contrôles sont les tests, le bilan doctor et l’essai réel des écrans. La livraison intègre la PR après contrôles verts ; les documents gardent 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. merge livre. sweep inventorie les attentes. Après le dernier lot, la recette est votre essai de la révision exacte avec accord daté. close livre puis retire le couloir après cette recette actuelle et votre confirmation explicite. Un contrôle rouge arrête la livraison jusqu’à correction.
lab plan demo
lab status demo
lab handoff
Mise à jour, retour arrière et retrait
Effectuez l’entretien depuis un terminal visible, hors de toute session d’agent vivante. Conservez le manifeste, les sauvegardes et les versions : ils permettent d’attribuer les fichiers et de reprendre une interruption sans effacer des réglages tiers.
Sur une installation distribuée, update vérifie le catalogue et l’archive, montre le plan et demande votre accord ; sans catalogue raccordé, gardez la version actuelle. update --rollback restaure hors ligne la précédente vérifiée, seulement si elle existe. Après réussite, vérifiez la version et doctor. Un checkout --dev ne passe pas par cette mise à jour de release.
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. Une panne de mise à jour relève de update --resume ; une pose ou un retrait interrompu peut relever de uninstall --resume selon le diagnostic. Corrigez d’abord la cause signalée, ne supprimez pas le journal.
lab uninstall --dry-run
Limites connues
Ce guide décrit le package 0.1.0, encore en français. Il n’existe ni option de langue ni commande onboard. Les exemples EN conservent les commandes et expliquent les sorties françaises. Acquisition après achat, activation distante, distribution privée et réception effective du support seront vérifiées lors du raccordement.
Les exemples de démarrage utilisent une copie locale contrôlée. Les tests isolés des commandes d’entretien ne prouvent pas un catalogue de production. Le site ne charge aucun service de diagnostic et ne demande jamais votre clé pour préparer un e-mail.
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.
Depuis un dépôt Git existant, nom 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 le choix (précisez codex pour ce guide).
É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. --lot 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.
Crée .worktrees/<couloir>, sa branche, ses métadonnées et la fiche de qualification ; installe normalement les dépendances puis ouvre cmux. WORKTREE, BRANCH et LOT permettent de retrouver le résultat. Si le couloir existe déjà, utilisez open ; ne recréez pas son worktree à la main.
open · Retrouver l’onglet
lab open [projet] <couloir> [--agent claude|codex] [--prompt <texte>|-]
Secours depuis le dépôt ou le couloir : retrouve l’onglet existant ou le recrée. --agent conserve le choix du couloir ; --prompt donne un texte, et - lit ce texte sur l’entrée standard.
Peut écrire la cible cmux et lancer une session. Ne décide pas du prochain lot. Si cmux est introuvable, ouvrez l’application et vérifiez sa commande avant de réessayer. Ne lancez pas une seconde session si la première travaille encore.
next · Continuer
lab next [projet] <couloir> [--agent claude|codex] [--goal <critères>] [--auto]
lab next [projet] <couloir> --lot <slug> [--kind feat|fix|chore] [--title <texte>]
Après le bilan, relit la fiche et sa Reprise pour lancer, reprendre, ouvrir le lot suivant livré ou la recette. --goal complète l’objectif ; --agent choisit l’agent. --auto remplace la session propriétaire dans le même onglet après enregistrement de sa Reprise.
--lot impose le prochain lot ; pour un retour en recette, utilisez --kind fix, puis --title si utile. Cette forme peut créer branche et fiche. L’ancienne option --merge est acceptée mais ne fusionne rien. next ne fusionne ni ne retire. Une session concurrente ou une livraison manquante impose de terminer l’étape indiquée avant de relancer.
Appelé par l’onglet, pas à taper manuellement : reconstruit le Goal complet depuis la fiche et devient le processus de l’agent. --agent choisit l’agent ; --goal ajoute un court complément.
Conserve les limites de longueur et le verrou de session. Le lancement automatique utilise encore le nom court lab : si un autre outil occupe ce nom, les appels directs par treelab restent possibles, mais cette ouverture automatique n’est pas garantie. Si la fiche ou le Goal manque, complétez le document puis utilisez next. Un long complément doit être écrit dans la fiche, pas dans une ligne de lancement.
plan · Voir la progression
lab plan [projet] [--json]
Depuis le dépôt enregistré, calcule les lots faits/total et les phases à partir des fiches vivantes, puis du checkout principal.
Ne modifie pas les documents. Tableau lisible sur stderr, champs ou JSON sur stdout. Si le plan est vide, créez le premier couloir avec new ; un ancien layout demande un treeplan à la prochaine planification.
list · Lister les couloirs
lab list [projet]
Avec projet, décrit ses worktrees ; sans projet, inventorie le registre. Donne branche, lot, propreté et cible cmux.
La lecture de verrou peut purger un verrou dont le processus est mort. Si un projet manque, vérifiez init depuis sa racine, sans recréer ses fichiers de travail.
status · Lire l’état courant
lab status [projet]
Avec projet ou depuis un dépôt connu, décrit le checkout principal et ses couloirs : LOT_STATE, LANE_PHASE, LAST_LOT, CLEAN et LOCK.
Peut purger des verrous périmés lors de leur lecture. Une session vivante reste protégée. Si le projet est indéterminé, précisez le nom enregistré.
lot · Consulter les fiches
lab lot current
lab lot new [--title <texte>]
lab lot list
Depuis le couloir enregistré : current donne LOT, STATE, DOCS et TREEPLAN ; list liste les états. new crée une fiche dans le layout documentaire courant et ajoute son intention au treeplan ; --title fixe son titre.
Mécanisme avancé de gestion documentaire : new ne remplace pas next pour changer de branche et de session. Si le dépôt est inconnu, revenez dans le couloir enregistré ; ne créez pas une fiche concurrente pour contourner un lot actif.
handoff · Préparer la reprise
lab handoff [projet] [slug] [--template]
Depuis le couloir, lit la section Reprise et le prochain lot. Si la section manque, ajoute le gabarit à la fiche et demande de le remplir ; sinon affiche la commande next quand le prochain lot est indiqué. --template affiche seulement le gabarit.
Ne livre pas le lot et ne vérifie pas la complétude des preuves. Renseignez objectif, lectures, preuves, reste et prochain lot avant de relancer, même si ACTION=prête est affiché.
merge · Livrer une demande de fusion
lab merge [projet] <slug>
Depuis le dépôt enregistré, slug désigne le couloir. Exige une PR vers staging si elle existe, sinon main, et un bilan vert. gh et les droits du distant sont nécessaires.
Fusionne après les contrôles, garde le couloir et les branches. Le dernier lot exige une recette actuelle. Un rouge, un conflit ou des droits insuffisants bloque ; corrigez la cause puis relancez. Si les contrôles restent en cours, la CLI peut armer la fusion automatique et sort sans annoncer une livraison acquise : vérifiez l’état distant.
close · Fermer après recette
lab close [projet] <couloir> [--confirm <couloir>]
Après le dernier lot, la recette est l’essai du résultat exact avec votre accord daté. close présente le retrait, puis exige une confirmation du nom du couloir. --confirm fournit ce nom après accord explicite déjà donné.
Livre le résultat validé puis retire le worktree et les seules branches attribuées avec preuve. Les fichiers non enregistrés, une session vivante ou une recette périmée bloquent. Enregistrez le travail et refaites la recette si le résultat a changé ; ne confirmez pas pour contourner un rouge.
sweep · Inventorier les attentes
lab sweep [projet] [--dry-run]
Depuis le dépôt enregistré, inventorie les couloirs et la raison de leur attente. --dry-run conserve le même comportement d’inventaire.
Ne retire rien, ne fait ni fetch ni prune. Le résultat indique la prochaine action sûre ; si le projet manque, précisez son nom enregistré. La fermeture reste une décision explicite par close.
doctor · Diagnostiquer
lab doctor [projet] [--root <checkout|worktree>] [--project-only] [--report|--freeze] [--json]
Sans projet, contrôle installation et registre ; avec projet, cible ce projet. --root choisit son checkout/worktree ; --project-only omet les contrôles globaux. Le bilan normal peut afficher des chemins privés : gardez-le local.
--report anonymise les deux flux sans écriture ni envoi ; --json structure stdout. Code 0 : aucun rouge ; 1 : contrôle rouge ; 2 : options ou diagnostic invalides. Corrigez la NOTE du bilan local. --freeze écrit la référence des mesures, uniquement pour un changement voulu et justifié au journal ; incompatible avec --report et jamais pour cacher un rouge. LAB_DOCTOR_SKILLS_WARN_LIMIT fixe un seuil facultatif entier positif ou nul, avertissement seulement.
setup · Installer les intégrations
lab setup [--dev] [--dry-run]
lab setup --reapply
Dans une distribution locale contrôlée, setup exige current vers cette copie. Pour un checkout de développement, ajoutez --dev ; ./install.sh délègue à ce mode. --dry-run affiche le plan sans installer de fichiers. --reapply, seul, réapplique les choix mémorisés d’une installation distribuée.
Après lecture du plan, saisissez j’accepte dans le terminal visible. Pose instructions, skills, agents, hooks, commandes et adaptation PATH annoncés ; garde les réglages étrangers et sauvegardes. Aucun agent vivant pendant l’opération. Si le plan change, relancez et relisez ; une panne de pose peut demander uninstall --resume. Approuvez ensuite les hooks dans l’agent si doctor le demande.
update · Mettre à jour ou restaurer
lab update [--rollback|--resume]
Installation distribuée seulement, hors session. update exige un catalogue fiable configuré par LAB_UPDATE_SOURCE ; la distribution privée authentifiée reste à venir. LAB_UPDATE_NOTICE=1 permet un rappel facultatif seulement si LAB_UPDATE_NOTICE_SOURCE est aussi configuré.
Vérifie version, archive et SHA-256 puis présente un plan avec consentement. Conserve sauvegardes et version précédente, remplace current et réapplique les choix. --rollback revient hors ligne à la précédente vérifiée ; --resume reprend une opération interrompue. Ces options sont exclusives. Catalogue absent ou précédente absente : gardez la version en place, n’inventez pas de source. Après succès, vérifiez --version et doctor.
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.
Appelés par l’outil avec du JSON sur stdin, pas à lancer manuellement. session-start fournit le contexte et le verrou ; session-end libère la session ; guard-bash et guard-tool examinent les opérations prévues.
Ces mécanismes peuvent écrire les métadonnées de session. Une erreur interne de hook ne bloque pas le travail. Si les intégrations sont inactives, consultez doctor et les approbations de hooks dans l’agent ; ne fabriquez pas de charge JSON pour contourner une protection.
help · Aide, version et formats
lab help
lab --help
lab -h
lab --version
lab plan [projet] --json
help, --help et -h affichent la même aide sur stderr et sortent à 2 : ce code ne signale pas une installation cassée. --version lit VERSION de la copie exécutée et produit VERSION=… ; --json transforme les sorties KEY=value en JSON.
Les explications restent françaises sur stderr, même avec --json. Un code non nul se lit dans le contexte de la commande ; doctor distingue 1 et 2. Une version absente demande de restaurer la copie complète. Aucune option de langue ni commande onboard n’est livrée.
Dépannage
Outil absent
Vérification et action
Vérifiez command -v pour git, jq, cmux et l’agent ; vérifiez macOS. Rendez l’outil accessible puis relancez le plan setup.
Résultat attendu
Chemin de chaque outil affiché, prérequis sans blocage.
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 ; ce cas reste limité dans le package actuel.
Dépôt non enregistré
Vérification et action
Depuis la racine Git voulue, vérifiez lab list puis lab init avec --root et --agent codex.
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 next --auto.
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 PR, tests distants, conflit, droits gh et recette du dernier lot. Corrigez la cause avant merge ; gardez le couloir.
Résultat attendu
Contrôles et bilan verts, puis PR réellement fusionnée.
Catalogue absent ou indisponible
Vérification et action
Lisez le diagnostic de update. Sans source fournie et vérifiée, gardez cette version. Si une source existe, vérifiez la connexion puis réessayez.
Résultat attendu
Aucun remplacement sur échec ; mise à jour seulement après catalogue et archive valides.
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.