If you’re running more than one coding task at a time, Git worktrees for agents give each worker its own directory without forcing you to clone the repository repeatedly. That matters because the annoying part of parallel agent work usually isn’t the code. It’s the collision: one worker changes the branch another worker is reviewing, a test run sees the wrong files, or a cleanup command deletes the checkout you still needed.
Git worktrees for agents start with one repository and several directories
A worktree is another working directory attached to the same Git repository. The repository keeps the object database and refs; each linked directory gets its own checked-out branch and index. Git documents the supported operations as add, list, lock, move, prune, remove, repair, and unlock. That gives the pattern a useful shape: one repository, multiple isolated working directories, and an explicit lifecycle for each one.
That’s different from making a second full clone for every worker. A clone can be perfectly valid, but it creates more copies of repository data and makes it easier to lose track of which checkout belongs to which branch. Git worktrees for agents keep the relationship visible through Git’s own bookkeeping.
The basic setup looks like this:
git switch main
git pull --ff-only
git worktree add ../project-agent-auth -b agent/auth origin/main
git worktree add ../project-agent-tests -b agent/tests origin/main
git worktree listThe branch names are the important part. Give every worker a branch that describes the task, and give every directory a name that makes the owner obvious. A directory called tmp2 is how future-you ends up debugging the wrong checkout at 2 a.m.
Give each worker a branch and a boring filesystem path
Parallel workers shouldn’t share a working directory. That sounds obvious until an agent starts a formatter, another agent changes a config file, and a third agent runs tests while both are halfway through edits. The output becomes impossible to attribute.
With Git worktrees for agents, each worker receives a directory such as ../project-agent-auth and a branch such as agent/auth. The worker can install local dependencies, edit files, and run tests without changing what another worker sees. The shared repository still makes commits and branch history visible to the reviewer.
Keep the directory outside the main checkout when practical. This makes accidental recursive searches less confusing and keeps a worker’s generated files from looking like untracked files in the primary checkout. It also makes removal straightforward: remove the linked worktree through Git, not by deleting a directory and hoping Git forgets it.
The source-backed rule is simple: use one linked working tree per branch. The operator rule is even simpler: write the path and branch into the task receipt before the worker starts.
Keep review boundaries explicit
Isolation is useful only if the review boundary is clear. A worktree doesn’t decide whether a change is good. It only prevents unrelated edits from being mixed together.
For each worker, record four things:
- the branch name;
- the worktree path;
- the exact acceptance command;
- the person or agent that performs independent review.
Then make the worker report a commit or a diff, not a vague sentence saying the task is done. The reviewer can inspect the branch, run the acceptance command in the same worktree, and compare the final files with the task receipt.
This is where Git worktrees for agents fit into a larger workflow. They’re infrastructure for separation, not a substitute for dependency tracking. A worker can still edit the wrong branch, forget to commit, or claim success after a failing test. The worktree makes those mistakes easier to detect because the artifact has a named home.
If the task produces generated files, put those files under the worktree or a declared artifact directory. Don’t silently write to a shared /tmp path. Shared temporary directories are fine for disposable build output, but they’re a bad place for the only copy of a review artifact.
Run tests from the worker’s directory
A test command should run from the worktree that owns the change. That keeps relative paths, virtual environments, generated fixtures, and Git state aligned.
cd ../project-agent-auth
python -m pytest -q
git status --short
git diff --check
git log -1 --onelineThe final three checks aren’t ceremony. git status shows whether the worker left untracked artifacts. git diff --check catches whitespace damage. The last commit identifies the artifact the reviewer is actually inspecting.
If two workers need the same base branch, create both worktrees from the same known ref and record that ref in the receipt. Don’t rely on the phrase “latest main” when reproducibility matters. A moving base branch turns a clean parallel layout into a moving target.
Clean up with Git, not with rm -rf
When a task is finished, inspect the worktree list before cleanup:
git worktree list --porcelain
git worktree remove ../project-agent-auth
git worktree pruneremove gives Git a chance to update its administrative records. prune cleans stale metadata after a directory disappeared outside Git. If a worktree contains uncommitted work, Git should make the removal fail rather than silently deleting it. That failure is valuable. It tells you the cleanup boundary isn’t actually complete.
Don’t remove a worktree just because the agent says it’s finished. Check the receipt, the commit, the review result, and any files that must be retained. A worker can be done while its evidence isn’t.
The pattern works best with a small control record
The useful version of Git worktrees for agents isn’t “make more directories.” It’s a small, auditable lifecycle:
- qualify the task and its source evidence;
- create a named branch and linked worktree;
- record the path, ref, and worker owner;
- run tests from that path;
- review the exact commit or diff;
- retain the receipt;
- remove the worktree only after the evidence is complete.
That lifecycle keeps parallel coding boring. Boring is the goal. The more agents you run, the less you want clever filesystem tricks hiding the actual branch state.
For a broader view of how I split agent work, see the Hermes async subagents guide. For the larger workflow map, the Codex use-case hub is the useful companion.
Git worktrees for agents aren’t a magic concurrency layer. They’re a clean isolation primitive. Pair them with named branches, explicit receipts, and independent review, and parallel work stops feeling like several people fighting over one keyboard.
Sources and evidence boundary
The Git and kernel manuals support the worktree operations and isolation model. The local hands-on receipt covers the commands used for this guide. It doesn’t claim that every repository, filesystem, or agent runner behaves identically. If a repository uses unusual hooks, submodules, or generated state, test the cleanup path before turning it into an automated worker default.
