Why AI Agent Worktrees Miss Uncommitted Changes
Prepared and checked using AI. Sources are linked in the article.
If an AI agent worktree appears to miss uncommitted changes in your main checkout, it is because the new checkout has its own files and staging area. A new worktree checks out a commit; it does not copy edits from another directory, even if those edits are staged. To give the agent that work, commit it before creating the worktree, apply a stash in the agent worktree, or transfer a patch. Git worktrees share repository data but keep their working trees, HEAD, and indexes separate.
What the new worktree contains
Suppose your main checkout has an edited src/auth.ts, a staged change to tests/auth.test.ts, and a new untracked file. You create an agent worktree from the current HEAD. The agent gets the versions of tracked files in that commit. Your edited file, staged test, and untracked file remain in the main checkout. Staging a change prepares it for a commit in that checkout; it does not publish it to the other worktree.
This distinction is useful when agents work independently. It also explains a common failed prompt: telling an agent to “continue the changes I made” gives it an objective, but does not put those files in the agent’s checkout. Git worktrees do not set filesystem permissions; whether the agent can read the main checkout directly depends on its permissions. If the task depends on those files being in the agent’s checkout, transfer a deliberate snapshot before the agent starts. For more on the isolation itself, see Git Worktrees: Why AI Agents Need Them.
Check what the agent is missing
Run these commands in the main checkout before choosing a transfer method:
git status --short
git diff
git diff --cachedgit status --short reports staged, unstaged, and untracked changes. In its two-column output, the first column describes the index and the second describes the working tree; ?? marks an untracked path. git diff shows unstaged tracked edits, while git diff --cached shows staged edits. Check both: a file can have one version staged and further edits left unstaged.
Write down which files the agent actually needs. A generated build directory, a local environment file, or an unrelated draft need not accompany a source change. The transfer methods below have different scopes: a commit is a durable starting point, a stash is convenient for an existing set of edits, and a patch can select paths without changing the main checkout.
Option 1: Commit a shared starting point
Choose a commit when the edits form a coherent base that the agent should build on. For example, if the relevant files are src/auth.ts and tests/auth.test.ts, stage and inspect them in the main checkout:
git add -- src/auth.ts tests/auth.test.ts
git diff --cached
git status --short
git commit -m "Prepare auth changes for agent"
git worktree add -b agent/auth ../agent-auth HEADgit add updates the index with the selected files’ current contents, and git commit records the index as a new commit. Inspect the staged diff before committing: previously staged, unrelated changes would also enter a plain git commit. The final command creates an agent branch and worktree at the new HEAD, so the agent begins with the committed base.
This approach gives both branches an explicit point of agreement. It does change the main branch’s local history. Use it when that base belongs in history; use a stash or patch if you still need to decide what to commit. Also check git status --short afterward for edits left out of the commit. Those edits remain local to the main checkout.
Option 2: Apply a stash in the agent worktree
A stash works when you want to hand over the current staged and unstaged changes without making a commit first. Run the first two commands in the main checkout:
git stash push -u -m "agent starting point"
git worktree add -b agent/auth ../agent-auth HEADThen enter the new worktree and apply the saved state:
cd ../agent-auth
git stash list
git stash apply --index 'stash@{0}'
git status --shortgit stash push saves changes and rolls them back in the checkout where it runs; -u includes untracked files. The stash is reachable from the linked worktree because stash entries live under a shared repository ref. git stash apply keeps the entry available, while --index tries to restore which changes were staged. Check git stash list before applying: stash@{0} means the latest entry and can refer to a different stash if another one was created meanwhile.
The main checkout is clean immediately after stash push. If you want the same starting edits there too, return to the main checkout and run git stash apply --index 'stash@{0}' there, then inspect its status. Applying the snapshot twice gives two independent copies of the edits. Decide later which copy should become the shared result; otherwise you may duplicate the same changes during integration.
Use apply while either copy might still be needed. pop removes a stash after a successful application, which is less suitable when the main checkout may also need the snapshot. Applying onto a worktree that has already diverged can conflict, so establish the base before asking the agent to edit it. An existing agent worktree can receive the stash too, provided you check its current changes and base first.
Option 3: Transfer selected paths as a patch
A patch is useful when the agent needs only some tracked files and you want to leave the main checkout as it is. Run this in the main checkout, using the selected paths as an example:
git diff --binary HEAD -- src/auth.ts tests/auth.test.ts > ../agent-auth.patch
git worktree add -b agent/auth ../agent-auth HEADThen, in the new worktree:
cd ../agent-auth
git apply --check ../agent-auth.patch
git apply ../agent-auth.patch
git status --shortgit diff HEAD includes the current tracked file contents relative to the commit, whether changes are staged or unstaged. --binary makes a patch that can carry binary changes. git apply --check checks whether a patch will apply; git apply then changes files without creating a commit. If the check fails, inspect the worktree’s base and existing edits before trying to resolve the mismatch.
This patch gives the agent the selected files’ current content, not the main checkout’s staged versus unstaged split. It also omits untracked files, since they are not part of git diff HEAD. If the agent needs a new file, stage it before making the patch, use the stash method with -u, or commit it as part of the base. Keep the patch outside the repository worktrees so it does not appear as an unrelated untracked file in the agent’s task.
Check ignored files and task boundaries
An ignored file is another possible missing input. To see whether an exclude rule applies to a path, run, for example:
git check-ignore -v -- .envgit check-ignore -v prints the matching exclude pattern and path. The stash method’s -u includes untracked files but does not include ignored files; git stash push --all includes ignored files too. Avoid using --all as a blanket fix for an agent task: it can sweep up local data unrelated to the requested code change. Give the agent only the configuration or fixture it needs, through the project’s normal local setup.
Once the agent starts, edits made in the main checkout still will not appear automatically in its worktree. If its assignment changes, send a new commit, stash, or patch and tell the agent which files or behavior changed. Before integrating the result, inspect the agent branch’s diff against its starting point. The workflow for bringing branches together is covered in How to Merge Work From Parallel AI Agents.
Where Parallel Code fits
Parallel Code is our free, open-source desktop app for macOS and Linux. It runs AI coding agents in parallel, each in its own git worktree, and provides a diff-first review surface. Give each agent the required starting changes using the same commit, stash, or patch decision described above.
Frequently asked questions
Why can’t the agent see changes I already staged?
Staging changes the index of the main checkout. A linked worktree has its own index, so its agent will see those contents in that checkout only after you commit them or transfer them into that worktree. Include both staged and unstaged edits when deciding what the agent needs.
Can I give the agent uncommitted changes without committing them?
Yes. Apply a stash in the agent worktree, or generate a patch from the main checkout and apply it there. A stash with -u can include untracked files; a git diff HEAD patch covers selected tracked paths and any new files you staged first.
Will the agent pick up edits I make after it starts?
No. Each worktree’s files continue to change independently. Transfer a later snapshot deliberately, and check for conflicts if the agent has edited the same files in the meantime.
Should I put the agent on my main branch to solve this?
A worktree created on a separate branch can start from a commit containing the required edits. Git normally refuses to check out a branch already in use by another worktree, and sharing one working directory would remove the file isolation the agent workflow relies on. Transfer the needed state instead of trying to make two worktrees share live edits.