How you can run multiple AI agents in parallel with git worktrees

One of the more capable capabilities of AI-assisted development is that you can put multiple AI programming agents to work simultaneously with little effort. for instance, you might have one creating a fresh capability, one cleaning up an old INTERFACE endpoint, and a third drafting a blog post. If the agents share a single build directory, they’ll stomp on each other’s changes. Worse, if any of them touches the data store, you’ll end up with corrupted check info that’s annoying to untangle.

Also Read: Tooling: How AI Content

The fix is to give each agent its own isolated environment. Git has a built-in capability called worktrees for this, but current development with databases and HTTP servers can be a real headache due to data store and port conflicts.

Hello devs, and welcome to the PHP Architect Channel! I’m Scott Keck-Warren, and today we’re talking about Git worktrees: what they are, how you can use them with agentic programming, and the gotchas that trip people up.

If you’re fresh here, we cover topics across the PHP scene. Hit subscribe so you don’t miss the next one.

What Is a Git Worktree?

When you work with a Git repository, you generally have one working directory. That’s the directory of files you set up and edit, and at any moment it has exactly one branch checked out. When you switch branches, Git rewrites the files in that single folder to match the fresh branch. It’s a straightforward fix to a complex issue.

With worktrees, Git breaks that one-to-one rule because you have one repository with multiple working directories, and each one can have a different branch checked out. They all share the same underlying Git history and objects, so you’re not cloning the build five times and wasting disk space on five copies of.git(which is the other fix to this issue).

Also Read: News: The Role of

Think of it like having multiple desks for the same job. Each desk has its own work spread out on it, but all the desks belong to the same office. You can walk between desks without cleaning up the one you’re leaving.

For parallel agent sessions, each agent gets its own desk. They read and write files freely without stepping on each other, because they’re in completely separate directories.

The Basic Commands

While it might seem complicated, three commands cover everything we need to do.

To set up a fresh worktree, usegit worktree addwith a path for the fresh directory location and the branch you want checked out there.

git worktree add ../capability-auth agent/auth-refactor

You’ll get output that looks something similar to:

Preparing worktree (checking out'agent/auth-refactor'
	
	) HEAD is now at d3ecfdc feat: add public episode show page with transcript utterances

That creates a sibling folder calledcapability-authwith theagent/auth-refactorbranch checked out, while your original folder stays exactly as you left it.

You can also set up a fresh branch from a specific point with a few more options.

git worktree add ../capability-payments -b agent/auth-payments main Preparing worktree (fresh branch'agent/auth-payments'
	
	) HEAD is now at d3ecfdc feat: add public episode show page with transcript utterances

To see all your worktrees, rungit worktree list.

git worktree list /Visitors/scottkeck-warren/Builds/UnleashedPostcasts d3ecfdc [main] /Visitors/scottkeck-warren/Builds/capability-auth d3ecfdc [agent/auth-refactor]

Clean up withgit worktree remove.

git worktree remove ../capability-auth git worktree list /Visitors/scottkeck-warren/Builds/UnleashedPostcasts d3ecfdc [main]

That deletes the folder and tells Git to forget about it without stashing or branch switching.

Also Read: How AI is Improving Customer Content Service | The Web Tier

Each Worktree Needs Its Own Working Files

A worktree is a fresh directory on disk as Git sees it. Anything that’s not tracked by Git (“vendor” directory, compiled assets, “.env” file, etc) won’t be in the fresh directory. Because of this, the first thing you do in any fresh worktree is set up the environment from scratch. To keep things straightforward, it’s best to do this using your Makefile with aconfiguration-worktreetarget.

cd
	
	../capability-auth make configuration-worktree

Running multiple agents in parallel means multiple copies of these files before anything starts. The configuration cost is real, but it’s smaller than troubleshooting a merge conflict between agents.

We’ll have more after this word from our partners.

Ports and Databases

In general, most current development environments require us to run a web host and at least one data store, but if you have multiple copies of your app running, they will step on each other.

for instance, if you start a local host in your main worktree, it will generally run on some default port.

PHP artisan serve

Inartisan serve‘s case, it’s going to use port 8000 by default.

Host running on[http://127.0.0.1:8000]
	
	

Go to another worktree and run the same command, and you’ll get a warning because port8000is already taken, andartisan servewill grab the next available port.

PHP artisan serve Failed to listen on 127.0.0.1:8000 (reason: Address alreadyin
	
	use) INFO Host running on [http://127.0.0.1:8001]. Press Ctrl+C to stop the host

Now we can accept this, but it can be hard to keep track of what port is assigned to which “build,” so it’s best to specify this in our “.env”:

# .env in the capability-payments worktree
	
	APP_URL="http://127.0.0.1:8001"
	
	

Then start each host on the matching port.

PHP artisan serve --port=8001

Separate databases matter more than separate ports. An agent running a move inshop_agent_authcan't wreck the schema inshop_agent_payments. Share a data store between agents that both run migrations, and you’ll get unpredictable schema state that’s slow to diagnose. It’s best to have the name of the data store match the branch so it’s simple to see what’s still valid (and you can write a cleanup script to automatically delete the databases).

# .env in the capability-payments worktree
	
	DB_DATABASE="feature_payment"
	
	

It’s best to make all of this part of yourmake configuration-worktreecommand.

Also Read: How AI and Machine Learning Are Enhancing eLearning Apps - News

Parallel Agent Sessions

Say you want two agents running simultaneously: one refactoring auth, one cleaning up payment processing. Start from your main branch and set up a worktree for each task.

git worktree add ../capability-auth -b agent/auth-refactor main git worktree add ../capability-payments -b agent/payment-cleanup main

Set up each one.

cd
	
	../capability-auth && make configuration-worktreecd
	
	../capability-payments && make configuration-worktree

Copy your.envto each worktree and refresh the port and data store name (unlessmake configuration-worktreedoes this for you), then it’s as straightforward as pointing each agent session at its own directory and letting them run.

Each agent finishes with a clean branch containing only its work so you can easily look the changes, merge it, and remove the worktree.

git worktree remove ../capability-auth

No conflict resolution between in-progress edits, no scrambled data store state. Each agent worked in its own environment and produced a reviewable branch.

Gotchas

In addition to the duplicate vendor, .env, and databases and the port conflicts issues, there are some common gotchas you’ll need to look out for.

The most annoying of which is that you can’t check out the same branch in two worktrees. Git enforces this because two directories editing the same branch might get messy. If you try, you’ll see an bug saying the branch is already checked out elsewhere. It’s best to always set up a fresh branch per worktree with the-bflag.

Also Read: Automating Code Deployment Alerts: Git → Sheets → Slack + AI Summary

AI agents may not know they’re in a worktree unless you tell them. Some agents, when they want to sync withmain, will rungit checkout maininside the worktree, which will fail becausemainis already checked out elsewhere. Set your agent instructions to avoid branch checkouts, or be ready to unstick it manually.

You need to worry about stale worktrees piling up. A worktree is a full directory so it consumes a non-zero amount of disk space. Rungit worktree listperiodically and remove the ones you’re done with, or better yet make it part of an automated script.

Docker adds an additional level of complexity, which we’ll discuss in a future write-up because it complicates this process but not extensively.

When to Use Worktrees and When to Just Stash

Worktrees earn their keep when you need two contexts alive at the same time: running agents in parallel, comparing behavior between branches, or keeping a hotfix branch running mid-capability. The isolation is the point of worktrees.

For a fast five-minute branch switch where you don’t need the old branch running, a plaingit stashor a throwaway WIP commit's faster, lighter, and less likely to cause migraines. A fullcomposer set upto patch a one-line typo isn’t worth it, but worktrees pay off when sessions run long enough to justify the configuration.

What You Need to Know

1. A worktree is one repository with multiple working directories, each on its own branch.
2. Usegit worktree add,git worktree list, andgit worktree removeto handle them.
3. Every fresh worktree needs its owncomposer set upbecausevendorisn’t tracked.
4. Give each worktree a distinct port and a separate data store when agents might run migrations.
5. You can’t check out the same branch in two worktrees.
6. Agents may try togit checkout maininside a worktree and fail.

Read the original article: PHP Architect