Git worktrees for AI coding agents

1. Give the task its own checkout

A linked worktree gives a branch its own working directory. Your editor can stay in the original checkout while the agent edits the task checkout. Git history remains shared.

From a repository whose main branch is named main, check your current state, then create a new task branch and checkout. Use a different task name and an unused sibling directory for each task.

git status --short
 git worktree add -b agent/auth-docs ../agent-auth-docs main
 git worktree list

Open ../agent-auth-docs in the terminal or editor where the agent will run. Install the project’s dependencies there and use its documented test commands. Confirm the agent’s working directory before it writes files. Creating a worktree does not automatically redirect an already-running agent.

Keep task branches distinct: Git normally prevents checking out the same branch in two worktrees at once. Committed work is the starting point; uncommitted edits in your main checkout are not copied into the new one.

2. Review the task, not just its final message

Inspect uncommitted edits in the task checkout. After the task changes have been committed to its branch, compare those commits with main.

git -C ../agent-auth-docs status --short
 git -C ../agent-auth-docs diff
 git log --oneline main..agent/auth-docs
 git diff main...agent/auth-docs

git diff without a revision shows unstaged edits; add --cached to inspect staged edits. The three-dot comparison shows committed task changes since the merge base. It is not a replacement for checking the combined result when both branches have moved.

Read the diff, check for unrelated files or secrets, and run relevant tests. A test result applies to the code and environment actually tested, not to a later integration commit.

3. Fast-forward only when the history permits it

Before integrating, return to main and preserve any local work. Do not run a merge over edits you have not decided how to keep.

git switch main
 git status --short
 git merge --ff-only agent/auth-docs

--ff-only succeeds when main is an ancestor of the task branch. If you have committed new work on main while the agent made different commits, the histories can diverge. A refusal is useful: nothing should silently overwrite your work.

For a diverged task, choose an integration strategy deliberately. One option is a separate integration worktree based on current main:

git worktree add -b integrate/auth-docs ../integrate-auth-docs main
 git -C ../integrate-auth-docs merge --no-ff agent/auth-docs

If there are conflicts, resolve and commit them in the integration checkout. Run the project’s tests there and review the combined diff. Only then bring that integration branch into a clean main checkout, using --ff-only again. If main moves during this process, reassess the integration; do not force it.

After integration, preserve any remaining task edits before cleanup. Git’s normal removal and branch-deletion checks protect unmerged or dirty work:

git worktree remove ../agent-auth-docs
 git branch -d agent/auth-docs

4. Separate files do not mean separate services

Where possible, make a test service report its commit SHA and have browser or integration tests check it. A healthy endpoint can still be the wrong instance.