From your Git repository to your first lane, followed by the commands to continue and find your way back.
Text remains selectable. Check paths before pasting a command into your terminal.
Prepare your Mac
You need macOS 13 or later, Git, jq, cmux and at least one available agent command. This guide uses Codex with access already configured in your terminal. On a fresh account, sign-in and hook approval still need completing before the agent can work. Third-party accounts, access and subscriptions are separate. gh and GitHub permissions are needed to deliver a PR, not to read this guide.
In a visible terminal, check the system and commands below. Each command -v should print a path; if missing, install the tool or make it available in PATH and check again. Open cmux before creating the lane. Setup can prepare cmux through Homebrew when it is available, after separate consent.
sw_vers -productVersion
git --version
jq --version
command -v cmux
command -v codex
Install from a local copy
The available path starts with a complete local copy whose origin you have checked. Private download after purchase and remote activation are still upcoming. Do not run an advertised remote bootstrap that has not been verified. The package, its messages and consent answers remain French.
From the root of that copy, check the version. A prepared distribution has .release and current pointing to that copy: use ./bin/lab setup --dry-run, then ./bin/lab setup. For a development checkout, the two commands below use --dev. Do not create .release to turn a checkout into a distribution.
Finish agent sessions before installing. The plan identifies affected instructions, skills, hooks, commands, shell profile and backups. Read it before running the actual command; type j’accepte (“I accept”) only if you agree. RESULT=simulated means a preview; RESULT=installed confirms installation. If consent is refused or the plan changed, nothing is installed: reread and retry.
./bin/lab --version
./bin/lab setup --dev --dry-run
./bin/lab setup --dev
Check the installed command
Open a new terminal to pick up PATH changes. The distributed command is treelab; lab is its short name when available. If lab belongs to another tool, keep it and use treelab for direct calls. Package 0.1.0 limitation: new tabs still execute lab launch. Automatic startup in this guide therefore assumes lab resolves to Treelab in those tabs. If that name is occupied, keep the other tool and seek help before continuing that step.
The version should match the verified copy (VERSION=0.1.0 for the documented revision). doctor explains checks through NOTE: fix each failed check and approve hooks in the agents when requested, then rerun. A local licence check does not prove remote activation. The regular diagnostic may contain private information: keep it on your Mac.
treelab --version
treelab doctor
command -v lab
Create your first lane
A project is your registered Git repository. A lane (couloir in the package) is an isolated working copy under .worktrees/ for one need. A batch (lot) is a verifiable step with a branch and document. Its Goal states the result that must be proved.
In the examples, replace /chemin/vers/depot with an existing Git repository root containing a first commit, demo with its chosen registry name, and premier with the name of your need. The main checkout should be clean. init registers it locally without adding documents there. --docs repo places them in the future lane. An offline fetch warning is distinct from registration failure: check PROJECT and ROOT.
new creates .worktrees/premier, a branch and docs/lots/premier/lot-01-premier.md, then opens a cmux tab. It may install repository dependencies. The agent starts by clarifying the need and writing the plan and document; opening the tab does not prove a batch has been executed. Find the scoping question and answer in that tab.
If the folder exists but the tab is missing, use lab open demo premier after checking the session. Do not rerun new to recreate an existing lane. After planning and ending that session, lab next demo premier opens execution with the document’s Goal.
In the lane tab: clarify → plan → execute → verify → deliver. Checks include tests, the doctor diagnostic and actually trying the screens. Delivery integrates the PR after green checks; documents retain evidence and a Reprise handoff readable without the agent’s memory.
next reads state and selects the next step; it neither merges nor removes anything. merge delivers. sweep inventories waiting lanes. After the last batch, acceptance testing means trying the exact revision with your dated approval. close delivers and removes the lane after current acceptance and explicit confirmation. Failed checks stop delivery until fixed.
lab plan demo
lab status demo
lab handoff
Update, rollback and removal
Perform maintenance in a visible terminal outside any live agent session. Keep the manifest, backups and versions: they establish file ownership and allow interrupted operations to resume without erasing unrelated settings.
On a distributed installation, update checks the catalogue and archive, shows the plan and asks for consent; without a connected catalogue, keep the current version. update --rollback restores the verified previous version offline, only if present. After success, check the version and doctor. A --dev checkout does not use this release update path.
For removal, inspect uninstall --dry-run, then run uninstall or uninstall --keep-state to keep the active installation manifest marked as removed. The registry is always preserved; without this option, the completed manifest is archived with backups. Backups remain at the printed path; separate dependencies are not removed. Interrupted updates use update --resume; interrupted setup or removal may require uninstall --resume as reported. Fix the stated cause first; do not delete the journal.
lab uninstall --dry-run
Known limits
This guide describes package 0.1.0, still in French. There is no language option or onboard command. English examples preserve commands and explain French output. Post-purchase acquisition, remote activation, private distribution and actual support receipt will be verified when connected.
Getting-started examples use a verified local copy. Isolated maintenance tests do not prove a production catalogue. This site loads no diagnostic service and never requests your key to prepare an email.
Command reference
Square brackets mark optional arguments, angle brackets mark values to replace, and | marks a choice. These are reference syntaxes, not lines to paste unchanged. projet is optional when the current folder identifies the registered repository. Names and options remain those of the French package.
Run from an existing Git repository. nom names the project; --root selects its root. --docs repo puts future documents in worktrees; local keeps them outside Git. --owner shared|other describes ownership without authorising writes to the main checkout. --agent selects the agent (use codex for this guide).
Writes the local registry, detects the base, remote and project commands; attempts a fetch. Leaves the main checkout unchanged. PROJECT and ROOT identify the registered repository. If the repository cannot be found, set --root to its Git root.
From the registered repository, choose a short lane name. --lot names the first batch, --kind selects the branch type, --base its base, --title its title and --agent its agent. --no-open skips the tab; --no-install skips project dependency installation.
Creates .worktrees/<couloir>, its branch, metadata and qualification document; normally installs dependencies and opens cmux. WORKTREE, BRANCH and LOT identify the result. If the lane already exists, use open instead of creating its worktree manually.
open · Find the tab
lab open [projet] <couloir> [--agent claude|codex] [--prompt <texte>|-]
Recovery command from the repository or lane: finds the existing tab or recreates it. --agent records the lane agent; --prompt supplies text, while - reads text from standard input.
May write the cmux target and start a session. Does not select the next batch. If cmux is unavailable, open the application and check its command before retrying. Do not start a second session while the first is working.
next · Continue
lab next [projet] <couloir> [--agent claude|codex] [--goal <critères>] [--auto]
lab next [projet] <couloir> --lot <slug> [--kind feat|fix|chore] [--title <texte>]
After the progress report, reads the batch and its Reprise handoff to start, resume, open the next batch after delivery, or begin acceptance testing. --goal adds criteria; --agent selects the agent. --auto replaces the owning session in the same tab after saving its handoff.
--lot forces the next batch; use --kind fix for acceptance feedback and --title when needed. This form may create a branch and document. The legacy --merge option is accepted but performs no merge. next neither merges nor removes a lane. If another session is alive or delivery is missing, finish the reported step before retrying.
Invoked by the tab, not a manual step: reconstructs the full Goal from the document and becomes the agent process. --agent selects the agent; --goal adds a short supplement.
Enforces length limits and the session lock. Automatic startup still uses the short name lab: if another tool owns that name, direct treelab calls remain possible but automatic opening is not guaranteed. If the document or Goal is missing, complete it and use next. Put a long supplement in the document rather than the launch line.
plan · See progress
lab plan [projet] [--json]
From the registered repository, computes completed/total batches and phases from live documents, then the main checkout.
Does not modify documents. Readable table on stderr, fields or JSON on stdout. If empty, create a first lane with new; an older layout needs a treeplan during the next planning session.
list · List lanes
lab list [projet]
With projet, describes its worktrees; without it, lists the registry. Shows branch, batch, clean state and cmux target.
Reading a lock may remove a stale lock whose process has exited. If a project is missing, check init from its root without recreating work files.
status · Read current state
lab status [projet]
With projet or from a known repository, describes the main checkout and lanes: LOT_STATE, LANE_PHASE, LAST_LOT, CLEAN and LOCK.
May remove stale locks while reading them. Live sessions remain protected. If the project is unclear, supply its registered name.
lot · Inspect batch documents
lab lot current
lab lot new [--title <texte>]
lab lot list
From the registered lane: current prints LOT, STATE, DOCS and TREEPLAN; list lists states. new creates a document in the current layout and adds its intent to the treeplan; --title sets its title.
Advanced document mechanism: new does not replace next for changing branch and session. If the repository is unknown, return to the registered lane; do not create a competing document to bypass an active batch.
handoff · Prepare a handoff
lab handoff [projet] [slug] [--template]
From the lane, reads the Reprise section and next batch. If the section is absent, adds the template to the document and asks you to fill it; otherwise prints next when the next batch is specified. --template only prints the template.
Does not deliver the batch and does not verify completeness of evidence. Record the objective, reading order, evidence, remaining work and next batch before retrying, even when ACTION=prête is printed.
merge · Deliver a pull request
lab merge [projet] <slug>
From the registered repository, slug is the lane. Requires a PR targeting staging when present, otherwise main, and a green diagnostic. gh and remote permissions are needed.
Merges after checks and preserves the lane and branches. The last batch requires current acceptance evidence. Failed checks, conflicts or missing rights block delivery: fix the cause and retry. If checks remain pending, the CLI may arm automatic merging and return without claiming delivery; check the remote state.
close · Close after acceptance
lab close [projet] <couloir> [--confirm <couloir>]
After the last batch, acceptance means trying the exact result and recording your dated approval. close presents removal and requires the lane name as confirmation. --confirm supplies that name after explicit approval has already been given.
Delivers the accepted result, then removes the worktree and only branches with proven ownership. Unsaved files, a live session or stale acceptance block it. Save work and repeat acceptance if the result changed; confirmation cannot override failed checks.
sweep · Inventory pending lanes
lab sweep [projet] [--dry-run]
From the registered repository, lists lanes and why they are waiting. --dry-run retains the same inventory behaviour.
Removes nothing and performs no fetch or prune. The result identifies the next safe action; supply the registered name if the project is missing. Removal remains an explicit close decision.
doctor · Diagnose
lab doctor [projet] [--root <checkout|worktree>] [--project-only] [--report|--freeze] [--json]
Without a project, checks installation and registry; with a project, targets it. --root selects its checkout/worktree; --project-only skips global checks. The regular diagnostic can show private paths: keep it local.
--report anonymises both streams without writes or sending; --json structures stdout. Exit 0: no failed check; 1: failed check; 2: invalid options or diagnostic. Fix the NOTE in the local diagnostic. --freeze writes the measurement baseline only for an intentional change justified in the journal; incompatible with --report and never a way to hide failures. LAB_DOCTOR_SKILLS_WARN_LIMIT sets an optional non-negative integer threshold, warning only.
setup · Install integrations
lab setup [--dev] [--dry-run]
lab setup --reapply
In a verified local distribution, setup requires current to point to that copy. For a development checkout, add --dev; ./install.sh delegates to this mode. --dry-run prints the plan without installing files. --reapply, used alone, reapplies saved choices from a distributed installation.
After reading the plan, type j’accepte in the visible terminal (“I accept”). Installs the announced instructions, skills, agents, hooks, commands and PATH adjustment; preserves unrelated settings and backups. No live agent session during the operation. If the plan changes, rerun and reread it; failed setup may require uninstall --resume. Then approve hooks in the agent if doctor requests it.
update · Update or restore
lab update [--rollback|--resume]
Distributed installation only, outside live sessions. update requires a trusted catalogue configured through LAB_UPDATE_SOURCE; authenticated private distribution is still upcoming. LAB_UPDATE_NOTICE=1 enables an optional reminder only when LAB_UPDATE_NOTICE_SOURCE is also configured.
Checks version, archive and SHA-256, then presents a plan for consent. Preserves backups and the previous version, switches current and reapplies choices. --rollback restores the verified previous version offline; --resume resumes an interrupted operation. These options are exclusive. If the catalogue or previous version is absent, keep the installed version and do not invent a source. After success, check --version and doctor.
Outside live sessions, inspect --dry-run first. Actual removal requires terminal consent. --keep-state preserves the active installation manifest marked as removed; --resume continues interrupted removal after its cause is fixed.
Removes only manifest-owned elements, restores backed-up settings and preserves unrelated changes. Keeps backups at the printed path and separately installed dependencies. The registry is always preserved. Without --keep-state, only the completed manifest is archived with backups. If the journal or an expected fingerprint no longer matches, preserve files and restore their integrity before resuming.
Called by the tool with JSON on stdin, not manual commands. session-start provides context and locks the session; session-end releases it; guard-bash and guard-tool inspect planned operations.
These mechanisms may write session metadata. Internal hook errors do not block work. If integrations are inactive, check doctor and hook approvals in the agent; do not craft JSON payloads to bypass a guard.
help · Help, version and formats
lab help
lab --help
lab -h
lab --version
lab plan [projet] --json
help, --help and -h print the same help on stderr and exit 2: that code does not mean installation is broken. --version reads VERSION from the running copy and prints VERSION=…; --json converts KEY=value output to JSON.
Explanations on stderr remain French, even with --json. Interpret a non-zero code in the command’s context; doctor distinguishes 1 and 2. A missing version requires restoring the complete copy. No language option or onboard command is shipped.
Troubleshooting
Missing tool
Check and action
Check command -v for git, jq, cmux and the agent; check macOS. Make the tool available, then rerun the setup plan.
Expected result
Each tool prints a path; prerequisites no longer block setup.
lab name occupied
Check and action
Compare command -v lab and command -v treelab. Use treelab without replacing the unrelated command.
Expected result
treelab --version identifies the right copy for direct calls. Automatic startup still calls lab: if occupied, preserve the other tool and contact support; this case remains limited in the current package.
Unregistered repository
Check and action
From the intended Git root, check lab list then lab init with --root and --agent codex.
Expected result
PROJECT and ROOT match the intended repository.
Missing tab
Check and action
Check lab status, open cmux, then use lab open with the existing lane name.
Expected result
The lane tab is found or recreated.
Session still alive
Check and action
Return to the owning tab and end the session normally. For automatic continuation by its agent, save the handoff before next --auto.
Expected result
Only one session works; maintenance is possible after it ends. Do not delete its lock.
Failed diagnostic
Check and action
Read NOTE in the local doctor output, fix the reported check and rerun the same diagnostic. --freeze is not a way to hide the failure.
Expected result
The check passes without artificially moving the baseline.
Blocked delivery
Check and action
Check PR target, remote checks, conflicts, gh permissions and final-batch acceptance. Fix the cause before merge; preserve the lane.
Expected result
Checks and diagnostic pass, then the PR is actually merged.
Missing or unavailable catalogue
Check and action
Read the update diagnostic. Without a supplied and verified source, keep this version. If a source exists, check connectivity and retry.
Expected result
No replacement on failure; update only after valid catalogue and archive.
Previous version absent
Check and action
Read the update --rollback refusal; preserve the current version and backups. Do not fabricate previous-release.
Expected result
Installation preserved; a reviewed report can accompany a support request.
Interrupted operation
Check and action
Fix the reported permissions or integrity issue, keep backups, then use update --resume for updates or uninstall --resume for removal requested by the diagnostic.
Expected result
Transaction completed or restored; check doctor before resuming work.
In your terminal, run lab doctor --report. Review stdout and stderr before sharing: this mode anonymises the existing diagnostic, not comments you add. The regular diagnostic without --report may contain private paths. Do not attach it unchanged.
lab doctor --report
Optional variant from a private local folder: choose a new filename, because > replaces an existing file. Exit 1 means a failed diagnostic check, not failed anonymisation; exit 2 means an error to resolve before sharing. The file receives stdout JSON; stderr stays in the terminal and must also be reviewed.
lab doctor --report --json > treelab-report.json
Check for names, personal paths, addresses, keys and project content. Remove unnecessary information, then add the report manually if you wish. This site does not read, receive or retain the file. The email link contains no diagnostic; only your email application can send it after your action.