Git worktrees for AI coding agents: the guide that includes what breaks
NOTE: publish here only AFTER the article is live on the site and an AI crawler
has read it (check Studio > AI crawlers). LinkedIn does not support canonical
tags, so the backlink below is the only signal that the site version is the original.
I lost a morning debugging behaviour that did not exist in the code I was reading.
The agent ran in a worktree whose vendor folder was a symlink to the main one. It was loading classes from the other branch, silently.
The command, and what it does
git worktree add -b agent/task ../project-task
cd ../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.
I wrote the full version, with the parts that did not fit here:
https://canvascode.app/en/news/git-worktrees-for-ai-coding-agents-guide
Top comments (1)
Been bitten by the autoloader variant of "the symlink can make the AI agent load code from the OTHER branch without warning", so seconding that one loudly. Two additions for the breakage list. First, git hooks are shared: hooks live in the common git dir, so when one agent's tooling runs something like a husky install, every other worktree inherits those hooks immediately, and an agent that rewrites a pre-commit hook changes behavior for all of its siblings. Second, dev server ports: worktrees copy the same port config, so the second agent either fails to bind or, worse, quietly talks to the first worktree's running server and reads state from the wrong branch, the runtime cousin of your vendor-symlink bug. On the threshold, I'd set it lower than three or four fronts: one agent plus a human editing the main checkout is already two concurrent writers, and that pair collides on a shared vendor dir just fine.