Git worktrees for AI coding agents: the guide that includes what breaks

Short answer: git worktree add -b name ../folder creates a copy of the project in another folder, tied to the same repository, on a separate branch. That is how each AI agent works without overwriting the others. What the guides skip is that the copy arrives with no node_modules, no .env and no build, and that is where most attempts stall.

The command, and what it does

git worktree add -b agent/task ../project-task\ncd ../project-task

That creates a new folder with every tracked file, on a new branch, sharing the same history. It is not a clone: the repository is the same, so commits are visible to everyone and no upload or download is involved. When done, git worktree remove ../project-task.

What does NOT come along (the part that stalls)

Only tracked files are copied. Everything .gitignore excludes stays behind, and that is exactly what the project needs to run:

• Dependencies (node_modules, vendor): must be installed in the worktree. A common shortcut is symlinking to the main folder, and for node_modules that usually works. For dependencies in languages that resolve file paths, such as PHP's autoloader, the symlink can make the AI agent load code from the OTHER branch without warning, and you end up debugging behaviour that is not in the code you are reading.
• Environment files (.env): a symlink is fine here, because it is a text file read once.
• Frontend build: if your framework looks for a generated manifest, it does not exist in the new worktree and the page breaks with an error that never mentions worktrees.

The database is shared, and that is a trap

A worktree does not isolate the database. If an AI agent runs a destructive migration, it hits the database every other agent and you are using. Worth stating explicitly in the project instructions, and worth having tests use an in-memory database instead of your development one.

When it is NOT worth it

With one AI agent at a time, it is not: you pay the setup cost and gain no isolation, because there is nobody to collide with. It is also pointless for read-only work like investigating or explaining code, which writes nothing. Isolation exists for concurrent writes, and only pays off from three or four simultaneous fronts.

Worktree or container?

A worktree is lighter and faster: files on the same disk, and the agent still sees the tools on your machine. A container isolates more deeply, including process and network, and it is what you want if you plan to leave an agent running unsupervised. For supervised work on your own Mac, a worktree is enough.

How to see who is in which worktree

git worktree list shows all of them with each branch. It is the command that answers "who is touching what" when you have five AI agents open and lost count.

What when two worktrees touch the same file?

It will happen, and the right thing is for it to surface early. With isolation, each works in its own copy and the collision appears at merge time, with Git showing both versions side by side. What you do not want is finding out through a test that started failing for no visible reason.