Git worktrees: running several coding agents in parallel

The problem: one folder for several agents

A coding agent works in a folder: it reads files, edits them, runs the tests and creates commits. As long as it is alone, all is well. As soon as you start a second agent on another task in the same folder, their changes mix: one rewrites a file the other is testing, one switches branch under the other’s feet, and one agent’s failing tests block the other’s delivery.

The usual answer is to clone the repository a second time. It works, but each clone downloads its own history, keeps its own settings and ends up drifting without anyone noticing. Git has offered something better for a long time: the worktree.

What is a git worktree?

A worktree is an additional working folder attached to the same repository. The git worktree add command creates that folder and checks out a branch in it. All worktrees share the same history and the same git objects: a commit made in one is visible in the others, with nothing to download.

Each worktree, however, has its own files, its own checked-out branch and its own state: what changes in one does not touch the others. Git even refuses to check out the same branch in two worktrees at once, which keeps one agent from overwriting another’s work without knowing it.

For a coding agent, this is exactly the right boundary: a folder of its own, a branch of its own, and the same repository as everyone else when it is time to deliver.

One task, one worktree, one branch

The rule that makes worktrees useful is simple: one task per worktree. A bug fix, a new page, a migration: each has its folder, its branch and its agent. The main checkout stays clean and never receives a commit; it is a reference, not a desk.

With Treelab, lab new does it all at once: it creates the worktree under .worktrees/, its branch, the first lot document and a tab in cmux where the agent starts. It also copies the local files you declared, such as an environment file, and installs the project’s dependencies from its lockfile.

You choose the agent of each worktree: Claude Code in one, Codex in another. Both receive the same skills, the same hooks and the same review agents, and lab launch hands the agent the objective written in the document, with nothing to copy.

$lab new project-1 feature-1 --title 'Add a search box' --agent claudePROJECT=project-1LANE=feature-1BRANCH=feat/feature-1BASE=origin/mainAGENT=claudelab: Next batches: unknown — planning will set them.$lab launch project-1 feature-1PROJECT=project-1LANE=feature-1AGENT=claudeSYNC=up-to-datePROMPT_BYTES=566

Running several tasks at the same time

Once each task lives in its worktree, you open as many as you need. Each agent moves forward in its tab, on its branch, without seeing the others’ files. You switch tabs to answer a question or approve a plan, then let the agent carry on.

The risk is no longer mixed files: it is losing track. lab status tells you where each worktree stands, with its branch, current lot, session and pull request. lab plan recomputes everyone’s progress from the documents at each display, with no board to keep up to date.

When two worktrees touch the same files, lab status reports that too: you know which task to deliver first, before the conflict arrives.

Deliver a worktree, then remove it

A worktree is not meant to last. Once the task is delivered it should go, or folders pile up and nobody knows which one is current. But removing it too early loses work: the classic mistake of a deletion run in the wrong place.

Treelab separates the two actions. lab merge delivers an intermediate lot after checking the report, the target and the pull request’s checks. At the end, you try the result; lab acceptance records your approval, then lab close delivers and removes the worktree, only after your explicit confirmation.

In the meantime, the guardrails refuse by default the operations that erase work, such as rm -rf outside the worktree or git reset --hard, and give the agent the safe alternative. The security page details what they cover, and what they do not.

Pitfalls to know

Dependencies: each worktree is a fresh folder, without node_modules or a virtual environment. They must be installed at creation, which lab new does from the project’s lockfile; --no-install skips it when you would rather do it yourself.

Untracked files: an .env file or a local key is not in git, so it is not in the new worktree. Declare them once, and Treelab copies them at every opening.

The agent’s context: an agent starting in a fresh worktree knows nothing about the task. Without a starting document, it guesses. That is why every Treelab worktree starts with scoping and a lot document, described in the guide to the lot method.

Vocabulary: lab’s messages call a task and its worktree a lane. Same thing, another name; the glossary also gives the former French words.

Where to start

To try worktrees by hand, git worktree add ../my-task -b my-task is enough, then git worktree remove once the work is merged. You will soon see what the discipline takes: naming, installing, copying, tracking and removing each folder at the right time.

To run them with a scoped agent, one document per lot and guardrails, Treelab installs everything in one command. The features page shows each command, and the pricing section details the licence.