Git worktree workflow for AI coding agents

A Git worktree gives each coding agent its own checked-out files and branch while the repository shares Git history. Use one worktree per bounded task, review each agent’s changes, and combine committed branches in a separate integration worktree. Separate directories keep working edits apart when each agent stays in its assigned worktree. They do not enforce access permissions or settle incompatible design decisions, shared service collisions, or merge conflicts. This guide walks through creation, inspection, integration, recovery, and safe removal with commands exercised in a disposable Git repository.

The examples are original illustrations, checked locally on a throwaway repository with Git branches named for a UI and API task. Replace the paths and branch names for your project. As of October 2026, the official git-worktree manual defines linked worktrees and their shared repository metadata; the git-merge manual defines conflict and abort behavior. The examples do not demonstrate a live coding-agent run, remote review, or deployment.

Why coding agents benefit from separate worktrees

Imagine two agents asked to change one application: one owns the account page and the other owns an API response. If they share a directory, a checkout, generated file, or dependency install can alter what the other sees mid-task. A linked worktree gives each agent a separate working directory, index, and checked-out branch. The lead can inspect a stable diff from each branch before bringing changes together. This is a useful filesystem boundary for parallel work, especially when agents run independent commands or need to pause and resume.

It is still one Git repository underneath. The worktrees share objects and most refs through a common Git directory, while each linked worktree has private administrative data such as its HEAD and index. The Git worktree details describe that split. A new commit on one branch becomes available by ref to the other worktrees, but it does not automatically modify their checked-out files. Git also normally refuses to check out the same branch in two worktrees, which helps prevent two directories from moving that branch independently.

Before creating directories, split the job by ownership: paths, expected behavior, interface assumptions, verification command, and the evidence each agent must return. Keep a single lead responsible for integration. A worktree cannot tell an API agent that a UI agent expects a newly renamed field. The API contracts guide covers that interface problem; the cross-client coordination guide covers decisions that must outlive one editor session.

Prepare a clean base and create one branch per task

Start from a reviewed base revision. The commands below assume your main checkout has no uncommitted work and origin/main is the agreed starting point. If your repository has unrelated local edits, preserve them and use an existing clean checkout or coordinate a new base with its owner. Never discard someone else’s working tree to make a tutorial command fit. Fetching updates remote-tracking refs; it does not by itself update main or change a teammate’s local files.

git status --short
git fetch origin
git worktree add -b agent/account-ui ../repo-agent-ui origin/main
git worktree add -b agent/account-api ../repo-agent-api origin/main
git worktree list

Run the commands from the repository checkout; choose sibling paths outside that repository directory. The -b option creates each new local branch at origin/main. It fails if the branch name already exists, which is a cue to inspect the existing work rather than reset it. git worktree list shows the paths, revisions, and branches that Git knows about. Give the UI agent only the UI path and the API agent only the API path. In a real repository, follow its documented package installation and verification commands separately in each directory.

A separate directory does not guarantee separate runtime state. Each worktree needs its own installed dependencies and build output when those live below the project directory. Processes can still contend for the same localhost port, database, cache, external account, or shared temporary path. Assign distinct ports and test data when simultaneous runs require them. Also check whether your toolchain climbs to a parent directory to find configuration; putting a worktree inside another repository can make discovery and file watching surprising. The sibling layout above avoids that nesting.

Give each agent a bounded assignment and inspect the result

A practical assignment names the branch and directory, the allowed paths, the behavior to implement, the relevant contract, and the exact proof requested. For example, the UI agent owns the account view and must report the changed paths, a focused test result, and any assumptions about the API response. The API agent owns the response and must report the same kind of evidence. If either needs to change a shared type, the lead resolves ownership before both edit it. Parallelism only helps when the tasks are independent enough to review separately.

1. Record the worktree path and branch before starting the agent; ask it to verify its current directory.
2. Ask for a concise diff summary, test command and actual result, and unresolved assumptions.
3. Review the diff against the stated ownership and the current base, including generated or untracked files.
4. Commit reviewed task changes on their task branches before integration, following the repository’s normal policy.

From the lead checkout, inspect each task branch explicitly. git -C makes the target directory unambiguous, so a shell left in the wrong worktree does not quietly read the wrong status. The following commands are read-only checks; a blank status means no uncommitted tracked or untracked changes are visible to Git in that worktree. It does not prove the code is correct, that ignored files are safe, or that its tests ran.

git -C ../repo-agent-ui status --short
git -C ../repo-agent-ui log -1 --oneline
git -C ../repo-agent-ui diff origin/main...HEAD --check
git -C ../repo-agent-api status --short
git -C ../repo-agent-api log -1 --oneline
git -C ../repo-agent-api diff origin/main...HEAD --check

The three-dot diff compares a branch with its merge base, which is useful for reviewing the work introduced by that branch. --check catches whitespace errors in the diff, not behavior errors. Read the actual changed code and run the relevant tests in the agent’s worktree. If the branch has moved far behind the agreed base, decide whether to update it before review; do not treat a clean status as proof that it will integrate cleanly.

Integrate on a separate branch and verify the combined result

Once both task branches contain reviewed commits, create an integration worktree from the agreed base. This keeps the original checkout available and makes the combined result a named branch. The following sequence is illustrative: it assumes the lead has authority to integrate and each merge begins with a clean worktree. A team using pull requests can submit this integration branch to its usual review and CI path; the command itself is not approval to merge to main or release.

git worktree add -b integrate/account-change ../repo-integrate origin/main
git -C ../repo-integrate merge --no-ff agent/account-ui
git -C ../repo-integrate merge --no-ff agent/account-api
git -C ../repo-integrate diff origin/main..HEAD --check
git -C ../repo-integrate status --short

Merge one branch at a time and stop after each result. Read the combined diff, run the application’s focused tests, then the required integration gate. Even nonoverlapping files can encode incompatible assumptions: the UI might send a field the API never accepts. The Git merge preflight guidance recommends starting with committed work because uncommitted changes can be difficult to reconstruct after a conflict. A passing task test belongs to its task revision; it is not evidence for the integrated revision until run there.

In the disposable fixture used for this article, UI and API branches changed different files. Both merges completed, git diff main..HEAD --check returned successfully, and the integration worktree had a blank short status. That is only a command-path check on a tiny fixture. It does not estimate how often real agent changes conflict or how long integration takes.

Recover from conflicts without discarding work

If a merge stops, first run git status inside the integration worktree. Git names the conflicted paths. Compare the task intent, the base, and both versions; then edit the files deliberately, run the relevant tests, stage the resolved files, and continue the merge. Do not ask an agent to choose a side merely because its version is newer. The official conflict guidance describes continuing or aborting a stopped merge.

git -C ../repo-integrate status
# After reviewing and editing each conflicted file:
git -C ../repo-integrate add path/to/resolved-file
git -C ../repo-integrate merge --continue

If the integration attempt is wrong and the worktree was clean before the merge, use git -C ../repo-integrate merge --abort to try to restore its pre-merge state, then inspect status again. Git warns that abort may not reconstruct uncommitted edits present when the merge began. Preserve and inspect those edits before choosing a recovery path. If the command reports it cannot abort, stop and examine the state; do not reset or delete the worktree reflexively. When an agent’s task branch needs a fix, make that fix on its branch and review the new commit before retrying integration.

Shared infrastructure failures need a different recovery path. If two test processes write to one database or use one port, stop the competing processes, isolate their configuration, and rerun the affected check. If both agents changed a contract, agree on the intended interface and update both sides together. Neither problem is repaired by moving worktree directories. For a broader handoff record, the PR-first workflow explains how to keep review and proof attached to a change.

Remove only finished, clean worktrees

After the integrated branch has passed the repository’s review path and the task branches are no longer needed as working directories, inspect each worktree again. Check for uncommitted, untracked, and ignored work you intend to retain; confirm the branch commits are still reachable by the integration branch or another reviewed ref. Then remove the finished worktrees with Git. The worktree options state that ordinary removal refuses an unclean worktree. That refusal protects material you may have missed; investigate it rather than adding a force flag.

git -C ../repo-agent-ui status --short
git -C ../repo-agent-api status --short
git worktree remove ../repo-agent-ui
git worktree remove ../repo-agent-api
git worktree list

Removing a worktree removes its working directory and administrative entry; it does not automatically delete the task branch. Decide whether to retain branch history under your repository’s retention policy. If a directory was manually moved, Git provides git worktree repair to reconnect its metadata. If it was manually deleted, inspect the branch and any surviving files before considering maintenance commands. Do not use forced removal as a routine cleanup shortcut.

Where a shared handoff fits

Git answers which commits and files exist. It does not record who is authorized to decide scope, what an agent promised to test, or whether a human approved a gated action. A small handoff should name the branch, paths, revision, actual checks, remaining uncertainty, and next owner. The agent handoff generator can format those details from what you enter. Its output is deterministic: it does not inspect a repository, run Git, execute tests, or verify the statements. Review the result before placing it in a work item.

If your team uses AppHandoff, its documented MCP endpoint is https://api.apphandoff.com/mcp. The current connection guide explains setup. Its served tools are bootstrap, get, find, ticket, plan, message, project, and decide_lifecycle_proposal. An agent with project access can use bootstrap and read a work item with get or find; an authorized write follows the tool’s current rules. A lifecycle approval card is for a signed-in human. A worktree and a passing test cannot grant that approval.

The repeatable pattern is simple: give each agent a bounded branch and directory, inspect the result it actually produced, integrate committed changes on a separate branch, test the combined behavior, and remove only clean finished worktrees. Keep a single owner for the decisions that cross those boundaries. That makes parallel coding easier to review without pretending that separate directories make software changes automatically compatible.