What is a git worktree?

In short

A git worktree is an extra working folder attached to the same git repository. Each folder has a different branch checked out, so you can work on two things at once without cloning the repo again, and keep parallel coding agents out of each other’s way.

How it works

Normally a repo folder has one branch checked out, and switching means committing or stashing first. With a worktree, your main folder stays put and a new folder with another branch is added next to it. The folders share commit history and the object database, but each has its own HEAD, index and working files.

The basic commands

A handful of commands covers day-to-day use.

git worktree add ../feature-a -b feature-a: creates a new branch and folder.
git worktree list: shows the open worktrees.
git worktree remove ../feature-a: removes the folder.
git worktree prune: cleans up records of folders deleted by hand.

Why it matters for coding agents

Two agents in the same folder can overwrite each other’s files, and one agent’s test run can trip over the other’s half-finished change. Giving each agent its own worktree avoids that: each works on its own branch and you combine the results with a pull request or merge. Branches that touch the same file can still conflict when you merge.

Things to watch for

Worktrees are lightweight, but a few details catch people out.

The same branch can’t be checked out in two worktrees at once.
Untracked files such as node_modules, .env and build output aren’t copied; you may need to install dependencies again.
If every worktree runs its own dev server, watch for port clashes.
Remove worktrees you’re done with, or forgotten folders pile up on disk.

Worktrees in AgentVera

AgentVera uses worktrees as the basis for running agents in parallel.

From the worktree panel in Git, open a branch and folder per feature and start an agent right in that folder.
In the night shift, each task runs in its own worktree on a night/<date>-<slug> branch; the agent commits but never pushes (Pro and Team).
Preview environments run the dev server of the project and of every worktree at its own address, named after the branch.
Agent coordination notes when agents in different worktrees change the same file, since the merge may conflict.

FAQ

What’s the difference between a worktree and a branch?

A branch is a named line of commits; a worktree is a folder where a branch is checked out. With branches alone you switch inside one folder; with worktrees you keep several branches open in separate folders at the same time.

How is a worktree different from cloning the repo twice?

Worktrees share one repository: commits, branches and config are common and they use less disk. A commit made in one worktree is visible from the others right away, while separate clones need push and fetch.

How do I delete a worktree?

Run git worktree remove <folder>. If you deleted the folder by hand, git worktree prune cleans up the record. The branch stays; delete it separately with git branch -d if you need to.

Do worktrees share node_modules?

No. Untracked files are separate in each folder, so you install dependencies in each worktree.