Git Worktree: The Right Way to Run Parallel AI Coding Agents

What Git Worktree Is

A standard Git repository has one working directory where you switch branches, edit files, stage, and commit. This model assumes you do one thing at a time. Switching from main to feat/login can be blocked by uncommitted changes, or those changes follow you into the new branch. git worktree decouples the repository from the working directory: one repository can mount multiple working directories, each checking out a different branch.

my-project/                 # main
├── .git/
├── src/
└── package.json

my-project-login/         # feat/login
├── .git                  # file pointing to main repo's Git metadata
├── src/
└── package.json

my-project-payment/       # fix/payment
├── .git
├── src/
└── package.json

All three directories belong to the same Git repository but maintain different file contents and branch states simultaneously.

Shared vs. Isolated

Commit, Tree, Blob objects — Shared. No need to duplicate full history per worktree.

Branch and tag refs — Shared. Commits made in one worktree are immediately visible in others.

Remote config, repo config, hooks — Usually shared. Changes may affect other worktrees.

Source files in working directory — Isolated. Each worktree has its own checked-out files.

HEAD — Isolated. Each worktree can point to a different branch or commit.

Staging area ( index ) — Isolated. git add in worktree A does not stage files in worktree B.

Uncommitted changes — Isolated. Changes in one worktree do not appear in another's git status.

Worktree is neither a full clone nor a simple directory copy. A fresh clone duplicates the entire .git object store and remote config; a plain copy cannot correctly maintain branch and staging state. Worktree shares the expensive repository history while giving each task its own "scene."

How Git Knows What You Changed

Git does not compare the main directory against the worktree directory. Each worktree owns its HEAD and staging area. Git compares three layers:

Working directory files → git add → Staging area (index) → git commit → Current branch's HEAD commit

git status

: summarizes state between working directory, index, and HEAD. git diff: shows working directory changes relative to the index. git diff --cached: shows staged changes relative to HEAD. git diff origin/main...HEAD: shows commits on current branch vs. target branch.

Git uses file status metadata and content hashes to detect changes efficiently, not by doing a folder-by-folder comparison between two working directories. This is why the outer repository typically ignores .worktrees/: the outer directory should not treat the entire worktree as a batch of new files; inside the worktree, its .git pointer makes Git use that worktree's own HEAD and index.

Complete Workflow: Create, Develop, Commit, Clean Up

1. Create the worktree

Place worktrees beside the main repo to avoid editors, build tools, or file watchers recursively scanning into them:

git fetch origin
git worktree add -b feat/login ../my-project-feat-login origin/main

Some AI coding platforms place worktrees inside the repo, e.g. my-project/.worktrees/feat-login. This layout eases platform management but requires adding .worktrees/ to .gitignore and verifying that IDEs, test runners, and indexers do not scan this directory.

List all worktrees attached to the current repository:

git worktree list

2. Explicitly run the AI inside the worktree

Creating the directory is only step one. When launching the AI coding tool, its working directory must point to the worktree:

cd ../my-project-feat-login
pwd
git branch --show-current
git status

If a platform schedules agents, it should pass at least:

Task ID: login-feature
Allowed working directory: /absolute/path/my-project-feat-login
Target branch: feat/login
Baseline branch: origin/main

Merely creating a worktree does not make the AI work inside it. If the executor's cwd still points to the main directory, the AI may continue modifying files there.

3. Modify and test

Inside the worktree, the AI or developer can install dependencies, edit code, and run tests normally:

cd ../my-project-feat-login
pnpm install
pnpm test

When a worktree is created, Git checks out only version-controlled files. node_modules, build artifacts, and local caches are not copied; they appear only after running install or build. With pnpm, package contents can be reused from the global store, but each worktree still maintains its own node_modules link structure.

4. Review and commit

Commit where you edit:

cd ../my-project-feat-login
git status
git branch --show-current
git diff
git add src/login.ts src/login.test.ts
git diff --cached
git commit -m "feat: add login flow"
git push -u origin HEAD

The commit object enters the shared Git object store, so the main directory can see the commit, but the main directory's current branch and files are not switched. You do not copy code back to the main directory or re-commit there. Later, create a Merge Request or Pull Request from feat/login as usual.

If the workspace contains multiple Git repositories, each is an independent commit unit; you must enter each corresponding worktree to commit.

5. Clean up after merge

Once changes are committed or no longer needed, run from the main repo:

git worktree remove ../my-project-feat-login
git worktree prune
git branch -d feat/login

If the directory still has uncommitted changes, Git refuses deletion by default. This is a safeguard; do not use --force unless you have verified the content.

Advantages of Worktree

1. Main workspace no longer interrupted by AI

You continue debugging, reading code, or hotfixing in the main directory while the AI works in an independent worktree. No branch-switching contention.

2. Parallel tasks get truly independent scenes

One agent fixes a bug, another adds tests, a third attempts a refactor. With separate branches and worktrees, file modifications and staging states stay isolated. This is far safer than letting multiple agents write to the same directory, and lighter than re-cloning for each task.

3. Clearer review boundaries

Task, branch, and directory form a one-to-one mapping:

One task → one branch → one worktree → one set of changes → one MR/PR

It becomes easier to answer "who changed this", "for which task", and "which group of changes should be discarded".

4. Lower failure cost

When an AI attempt fails, you can keep the worktree for further analysis or delete it entirely. The main working directory avoids repeated rollbacks, cleanups, and restores.

5. More stable context

Long-running agents do not suddenly face a completely different codebase because the developer switched branches. Stable paths, branches, and dependency environments reduce misjudgments.

Problems Worktree Introduces

Worktree is not a free lunch. It converts "branch-switching complexity" into "managing multiple working directories complexity."

1. Source code and dependencies consume disk

Each worktree checks out a full copy of version-controlled sources. If every directory installs dependencies and builds, each produces its own node_modules, caches, and build artifacts. A large monorepo with a dozen concurrent worktrees can consume significant disk space.

2. Humans and AI can enter the wrong directory

Directories look very similar — this is the most common and practical risk. Before committing, verify at least three things:

pwd
git branch --show-current
git status

AI executors should perform the same pre-checks at every task start and halt immediately if the path or branch mismatches.

3. Same branch cannot be checked out twice

Git normally prevents the same branch from being checked out in two worktrees. Running git switch feat/login in the main directory may error "branch already checked out at another worktree." This is not a bug; Git protects two working directories from simultaneously modifying the same branch state.

4. Toolchain may be unaware of worktrees

Tools that especially need checking:

Scripts with hard-coded absolute project paths.

Build tools that read config only from the main directory.

IDEs and file watchers that auto-scan all subdirectories.

Local services bound to fixed ports, databases, or cache directories.

Legacy tools that assume .git is always a directory, not a file.

Code is isolated, but ports, databases, container names, and external services are not automatically isolated.

5. Some Git state remains shared

Branch refs, repository config, hooks, and the default stash store still belong to the single repository. Certain repo-level operations in one worktree can affect others. Therefore, agents should not be granted unrestricted permission to delete branches, rewrite history, bulk-clean, or modify repository config.

6. Requires lifecycle management

Long-lived, uncleaned worktrees become a "directory graveyard": nobody knows if the task finished, if the branch was merged, or if the directory can be deleted. Platforms or teams should record: task ID, worktree path, branch, creation time, last activity time, and merge status, and provide a safe cleanup mechanism.

7. It is not a security sandbox

Worktree isolates Git working state only; it cannot restrict process permissions. An agent started inside a worktree, if it has full disk read/write access, can still use absolute paths or ../ to modify the main directory, read credentials, or touch other repositories. Real security isolation requires:

Explicit allow-listed paths.

Filesystem permissions or container sandboxes.

Command approval mechanisms.

Network and credential access controls.

Operation logs and diff reviews.

Why the AI Coding Era Needs Worktree More

Traditionally, a working directory maps to "one thing a developer is doing right now." AI coding changes this premise. A developer may review one agent's output while launching another to fix a bug; background agents may run tests or refactors for tens of minutes. When task throughput rises, a single working directory becomes a concurrency bottleneck.

Worktree's value is not making AI write faster, but making parallel work controllable:

Each agent gets a stable file context.

Each task has a clear branch boundary.

Failed results can be discarded wholesale.

Humans can review diffs independently.

The main workspace never has to yield to an agent.

In other words: Model capability decides what AI can write; workspace isolation decides whether those changes are manageable.

AI Coding Scenarios Where Worktree Is Strongly Recommended

Human and AI working simultaneously

You are developing or debugging in the main directory while wanting the AI to complete another coding task. Worktree avoids branch contention.

Multiple agents running in parallel

When each agent modifies files, runs formatters, or executes tests, give each task its own branch and worktree. Do not let multiple writing agents share one directory.

Long-running refactors or migrations

Cross-module refactors, framework upgrades, bulk code generation — long duration, wide scope — belong in a directory that can be reviewed or discarded at any time.

Main directory has uncommitted changes

You don't want to commit half-finished work or create a temporary stash just to let the AI work. Worktree can spawn a clean scene from a known-good commit.

Trying multiple approaches at once

Two agents implement approach A and approach B in separate worktrees, run tests independently, compare diffs, then decide which to keep.

High-risk automated fixes

Dependency upgrades, auto-fixes, bulk formatting may produce large unintended changes. An isolated worktree clarifies the risk boundary, though it still needs permission limits and human review.

Scenarios where worktree is usually unnecessary

AI only reads code or explains logic, no file writes.

Single person, single task, few-minute trivial change.

Current directory is clean and no parallel work exists.

Toolchain heavily relies on fixed absolute paths and isn't yet compatible.

Local disk is tight and the repo plus dependencies are huge.

Recommended Architecture for AI Coding Platforms

If you are building an AI coding platform, don't just expose a "create worktree" button. Worktree should be part of the task execution pipeline.

Strong binding between task and directory

Persist the relationship:

taskId → repository → branch → worktreePath → baseCommit

This lets the platform find the correct scene when resuming sessions, viewing diffs, continuing execution, or cleaning up tasks.

Executor must receive explicit cwd

Don't rely on the terminal happening to be in the right directory. The execution request must carry the absolute path and verify before running:

realpath(cwd) == registeredWorktreePath
currentBranch == expectedBranch
HEAD/baseCommit matches task expectation

Align "writable scope" with the worktree

The allowed write root should be limited to the worktree. Writes outside that scope must be rejected or require human approval. Remember: a prompt instruction "don't modify other directories" is not a security boundary; real permission control is required.

Run validation and commit in the same directory

Code edits, formatting, tests, diff, and commit should all happen inside the same worktree. Otherwise you risk "AI modified in A, but tests ran in B" false successes.

Cleanup only after merge and result confirmation

Platforms should auto-remove worktrees only when explicit conditions are met:

Changes committed and pushed.

MR/PR created or task explicitly abandoned.

No uncommitted files remain in the worktree.

User confirms the scene is no longer needed for recovery.

Adoptable Best Practices Checklist

Before creation

One writing task ↔ one branch ↔ one worktree.

Create from an explicit remote baseline, e.g. origin/main.

Use stable, traceable directory names, e.g. task-123-login.

Record baseCommit for accurate diff generation later.

Before execution

Verify pwd, current branch, and git status.

Set the agent's cwd explicitly to the worktree's absolute path.

Restrict the agent's allowed write paths and high-risk Git commands.

Assign different ports, container names, and cache directories for parallel services.

Before commit

View git diff first, then selectively git add.

Use git diff --cached to inspect final commit content.

Run relevant tests inside the current worktree.

Ensure .env, credentials, caches, or build artifacts are not staged.

Push the current branch with git push -u origin HEAD.

After completion

Confirm commit or MR/PR is recoverable.

Check worktree for any remaining uncommitted changes.

Remove with git worktree remove, not by deleting the directory directly.

Periodically run git worktree prune to clean stale records.

Treat Worktree as the AI's Workbench, Not a Safe

Git Worktree originally solved developers maintaining multiple branches in parallel. In the AI coding era, it gains a more critical role: giving every automated task an independent, observable, discardable code scene.

It keeps the main directory stable, prevents multi-agent overwrites, and makes every change easier to review and roll back.

But it does not automatically limit AI permissions, choose the correct directory for you, or manage ports, dependencies, and lifecycles.

The mature usage pattern is not "create a worktree and pray the AI doesn't wander," but to establish full constraints:

Task binds to directory → Pre-execution branch verification → Restrict writable scope → Test and review in same directory → Commit and push → Safe cleanup

Worktree is not the safety finish line for AI coding, but it is an essential starting point from "AI can edit code" toward "AI can be engineered and managed."

References

Git official documentation: git-worktree

Git official documentation: git-diff

Git official documentation: Repository Layout