Video version: https://youtu.be/uVKXmqYVjpQ

One of the more powerful features of AI-assisted development is that you can put multiple AI coding agents to work simultaneously with little effort. For example, you might have one building a new feature, one cleaning up an old API endpoint, and a third drafting a blog post. If the agents share a single project directory, they’ll stomp on each other’s changes. Worse, if any of them touches the database, you’ll end up with corrupted test data that’s annoying to untangle.

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

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

If you’re new here, we cover topics across the PHP ecosystem. 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 create 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 new branch. It’s a simple solution to a complex problem.

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 project five times and wasting disk space on five copies of .git (which is the other solution to this problem).

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 create a new worktree, use git worktree add with a path for the new directory location and the branch you want checked out there.

git worktree add ../feature-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 called feature-auth with the agent/auth-refactor branch checked out, while your original folder stays exactly as you left it.

You can also create a new branch from a specific point with a few more options.

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

To see all your worktrees, run git worktree list.

git worktree list
/Users/scottkeck-warren/Projects/UnleashedPostcasts  d3ecfdc [main]
/Users/scottkeck-warren/Projects/feature-auth        d3ecfdc [agent/auth-refactor]

Clean up with git worktree remove.

git worktree remove ../feature-auth
git worktree list
/Users/scottkeck-warren/Projects/UnleashedPostcasts  d3ecfdc [main]

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

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 new directory. Because of this, the first thing you do in any new worktree is set up the environment from scratch. To keep things simple, it’s best to do this using your Makefile with a setup-worktree target.

cd ../feature-auth
make setup-worktree

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

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

Ports and Databases

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

For example, if you start a local server in your main worktree, it will generally run on some default port.

php artisan serve

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

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

Go to another worktree and run the same command, and you’ll get a warning because port 8000 is already taken, and artisan serve will grab the next available port.

php artisan serve
  Failed to listen on 127.0.0.1:8000 (reason: Address already in use)

  INFO Server running on [http://127.0.0.1:8001]. 

  Press Ctrl+C to stop the server

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

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

Then start each server on the matching port.

php artisan serve --port=8001

Separate databases matter more than separate ports. An agent running a migration in shop_agent_auth cannot wreck the schema in shop_agent_payments. Share a database 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 database match the branch so it’s easy to see what’s still valid (and you can write a cleanup script to automatically delete the databases).

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

It’s best to make all of this part of your make setup-worktree command.

Parallel Agent Sessions

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

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

Set up each one.

cd ../feature-auth && make setup-worktree
cd ../feature-payments && make setup-worktree

Copy your .env to each worktree and update the port and database name (unless make setup-worktree does this for you), then it’s as simple 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 review the changes, merge it, and remove the worktree.

git worktree remove ../feature-auth

No conflict resolution between in-progress edits, no scrambled database 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 error saying the branch is already checked out elsewhere. It’s best to always create a new branch per worktree with the -b flag.

AI agents may not know they’re in a worktree unless you tell them. Some agents, when they want to sync with main, will run git checkout main inside the worktree, which will fail because main is 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. Run git worktree list periodically 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 article 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-feature. The isolation is the point of worktrees.

For a quick five-minute branch switch where you don’t need the old branch running, a plain git stash or a throwaway WIP commit is faster, lighter, and less likely to cause migraines. A full composer install to fix a one-line typo isn’t worth it, but worktrees pay off when sessions run long enough to justify the setup.

What You Need to Know

1. A worktree is one repository with multiple working directories, each on its own branch.
2. Use git worktree add, git worktree list, and git worktree remove to manage them.
3. Every new worktree needs its own composer install because vendor isn’t tracked.
4. Give each worktree a distinct port and a separate database when agents might run migrations.
5. You can’t check out the same branch in two worktrees.
6. Agents may try to git checkout main inside a worktree and fail.