How Git worktrees work

When several tasks move at once, each needs a clear scope and a place to be reviewed. Git worktrees provide that separation for code. They are worth understanding if you are coordinating work with coding agents, even when you are not writing every change yourself.

Worktrees do not make a full copy of your repository. They create an additional working directory that shares the same underlying Git history and object database. Each worktree has its own working directory and index, so uncommitted changes stay isolated to the folder where they were made, but all commits still go into the same shared repository.

The problem worktrees solve

If an agent is editing your repository for 15 to 60 minutes, your main working directory is no longer a safe place for unrelated work. Waiting wastes time. Interrupting throws away momentum.

Worktrees solve this by giving you multiple working directories for the same repository, each with its own checked-out branch.

The mental model

Think of a worktree as:

• One Git repository history and object store
• Multiple independent folders on disk
• One active branch per folder

So instead of one folder constantly switching branches, you have multiple folders, each stable on its own branch.

Create one

git worktree add ../games-worktrees/agent-track-17 -b agent/track-17 main

This command:

1. Creates a new folder at ../games-worktrees/agent-track-17
2. Creates a new branch agent/track-17 from main
3. Checks that branch out in the new folder

Now your main folder can stay on main while the agent works in the worktree. Your main folder can use another branch too.

Core rules and gotchas

1. You cannot check out the same branch in two worktrees at once.
2. Uncommitted changes are isolated to the folder where they were made.
3. Commits still belong to the same repository and can be merged normally.
4. You cannot delete a branch if it is currently checked out in any worktree.

Because all worktrees share the same underlying .git directory and object database, commits created in any worktree immediately become part of the same repository history.

To see active worktrees:

git worktree list

Reviewing an agent branch while it is active

If agent/track-17 is already checked out in its worktree, your main folder cannot check out that branch directly.

For quick inspection, switch to the latest commit in detached HEAD state:

git switch --detach agent/track-17

Detached HEAD means you are looking at a specific commit instead of a branch pointer. It is safe for inspection and testing as long as you do not create new commits there. If you need to make edits, choose one of these options:

1. Move into the worktree folder, or
2. Create a new branch from that detached commit

Cleanup

When work is merged and you are done:

git worktree remove ../games-worktrees/agent-track-17
git worktree prune

Why this works well with AI agents

In my workflow, each agent creates its own worktree and branch before writing code. The agent only touches that folder. I keep working in my main folder.

Concurrent tasks stay isolated, I rarely have to stash work, and every agent leaves behind a branch I can review.

I like the freedom to test an idea without disturbing the product people already use. Each experiment still needs a reason to exist and a decision about whether it should ship. More parallel work is useful when it helps answer those questions sooner.