Git worktrees for parallel AI coding

What a worktree isolates

A Git worktree gives a repository another working directory with its own checked-out files and index. You can keep the main branch open in one directory while a separate branch is edited elsewhere. The directories share repository history. This is useful when two AI coding tasks need to run without overwriting each other’s unfinished edits.

The Git worktree reference documents the commands and restrictions. In normal use, Git refuses to check out the same branch in multiple worktrees. Give each task a distinct branch and directory; do not bypass that safeguard to make parallel editing seem easier.

A worktree will not automatically install dependencies, copy ignored environment files, or provision a separate database. A task running on port 3000 can still collide with another server on port 3000. Before starting agents, decide which services and test data they may share.

Try it in a disposable repository

This walkthrough uses a new temporary directory, so it does not change your project. It needs Git and a POSIX-compatible shell. Download the complete demonstration script, inspect it, and run sh worktrees-demo.sh. The script prints the temporary location and leaves the final main repository there for inspection.

workshop=$(mktemp -d "${TMPDIR:-/tmp}/codeck-worktrees.XXXXXX")
git init -b main "$workshop/project"
cd "$workshop/project"
git config user.name 'Tutorial Example'
git config user.email 'tutorial@example.invalid'
printf '# Demo\n' > README.md
git add README.md
git commit -m 'Initial snapshot'
git worktree add -b codex/docs ../docs-task main
git worktree add -b codex/checks ../checks-task main
git worktree list

Read the diagram explanation

• project/. main · integration directory
• docs-task/. codex/docs · guide changes
• checks-task/. codex/checks · verification changes

The main argument fixes the starting point. Without an explicit base, it is easier to begin from an unintended checkout state. For a real project, verify the base branch and whether your current changes are committed before creating task directories. Uncommitted edits are not automatically copied into a new worktree.

Review and integrate

In this small example, the documentation task creates guide.txt and the verification task creates checks.txt. Commit each change in its own directory. The -C flag runs Git in the specified directory without changing your shell’s current location.

printf 'Documentation task\n' > ../docs-task/guide.txt
git -C ../docs-task add guide.txt
git -C ../docs-task commit -m 'Add guide'
printf 'Verification task\n' > ../checks-task/checks.txt
git -C ../checks-task add checks.txt
git -C ../checks-task commit -m 'Add checks'
git diff main...codex/docs
git diff main...codex/checks
git merge --no-edit codex/docs
git merge --no-edit codex/checks

Review the diffs before the merges. The three-dot comparison shows changes from the merge base to the task branch; see Git’s diff reference for the distinction from comparing two branch tips directly. In a moving real project, review the integrated result too: the base may have gained changes since the task began.

This demo deliberately uses different files. It does not prove that parallel edits to one API are compatible. If a merge conflicts, stop and inspect the conflicting requirements; do not choose a whole side simply to clear the conflict. Run the relevant tests after integration, including checks that span both contributions.

Clean up without losing work

Before removal, inspect git status in each worktree. Preserve uncommitted changes you still need. Once the branches are integrated and the directories are clean, remove the linked worktrees through Git and delete the merged branches.

git -C ../docs-task status --short
git -C ../checks-task status --short
git worktree remove ../docs-task
git worktree remove ../checks-task
git branch -d codex/docs codex/checks
git worktree list
git status --short

A refusal to remove a dirty directory or delete an unmerged branch is useful information. Inspect it instead of adding a force flag. Close task-specific servers when you finish. If your coding application manages its own worktrees, use its supported archive or cleanup flow so the app’s records stay consistent.

Worktrees make independent work easier to manage. Choosing good task boundaries still comes first; use the delegation guide before deciding how many branches to create.