Git worktrees for parallel coding agents
Updated 2026-09-13
Give each writing agent its own checkout
Use Git worktrees for parallel agents when two tasks need to edit the same repository independently. A worktree gives a branch its own checked-out files while sharing the repository's Git object storage. Two terminal windows in one directory still see the same files; two worktrees provide separate working directories.
The practical rule is one worktree per agent that writes code. For example, put search changes on feature/search and export changes on feature/export. Both agents can edit their own copy of package.json without overwriting the other's file on disk. Conflicts can still appear when you integrate the branches, so divide tasks along boundaries you can review.
A worktree provides separate files.
Processes still share your computer, network ports, and any external services their configuration names. Decide those resources alongside the branch assignment.
Create and inspect a worktree
Start in your repository on the commit you intend to use as the base. Inspect it before creating the new branch:
git status --short
git branch --show-current
git worktree add ../repo-feature-x -b feature/x
git worktree listThe add command creates branch feature/x from the current commit and checks it out in sibling directory ../repo-feature-x. Existing uncommitted changes in the original checkout are not copied into the new worktree. Commit or otherwise account for prerequisite changes before choosing a base.
Enter the directory and verify it before launching your agent:
cd ../repo-feature-x
pwd
git branch --show-current
claudegit worktree list shows the registered paths, commits, and branches. Use it when you forget which folder owns a branch. Git normally prevents checking out one branch in two worktrees at once; give another writing agent a different branch instead of forcing that protection aside. The Git worktree reference documents the commands and their options.
Name branches and folders so ownership is visible
Choose predictable pairs: feature/search in ../repo-search, fix/export-timeout in ../repo-export-timeout. Task names survive longer than labels such as agent-2, and they are easier to match to a pull request. Keep a short note recording the directory, branch, assigned agent, and test command.
Sibling folders avoid placing another checkout inside your main working tree. If you deliberately use a nested directory such as .worktrees/, add a root-anchored entry to the repository's .gitignore before creating worktrees there:
/.worktrees/This keeps nested checkout contents out of the parent checkout's untracked-file list. It does not isolate caches, ports, or services. Prefer the sibling layout in the command example unless a project convention requires nesting; it also makes accidental broad searches across several copies less likely.
Install dependencies and choose separate ports
A fresh worktree contains tracked files, so initialize its development environment. Do not assume ignored dependencies or generated output came across from the original checkout. For a Node project with a committed npm lockfile and package files at its root:
cd ../repo-feature-x
npm ci
npm testFor a monorepo, enter the package directory first. Follow the repository's existing package manager and setup instructions. Run installation separately in each worktree; sharing a writable node_modules directory through a symlink can mix dependencies from different branches.
Assign development ports explicitly. For two Vite projects whose dev script invokes Vite, example commands in their respective package directories are:
npm run dev -- --port 5173 --strictPortnpm run dev -- --port 5174 --strictPortUse ports that are free on your machine. --strictPort makes an occupied port a visible failure. Record the branch beside its preview URL so a reviewer does not accidentally inspect another agent's server. Apply the same separation to test databases, temporary directories, and other writable resources the project uses.
Check environment files and shared build caches
Ignored .env files are not part of the tracked checkout. Set up each worktree through your project's normal local configuration process, checking database names, service endpoints, and credentials. Copying an environment file without reading its destinations can point two independent branches at one mutable test database.
Check where the build writes. A cache under each worktree's own directory is distinct, but an absolute output path such as /tmp/repo-build is shared. Give mutable outputs separate paths where the tool permits it. Some package download caches support concurrent access; that does not establish that every compiler or generated-file cache does.
Ask each implementer to stay within its assigned directory. A worktree does not prevent an agent from being instructed to edit a sibling checkout. Before a test run, inspect pwd, the branch name, and any path overrides in the command. Isolation only helps when the process actually uses the isolated paths.
Choose manual Git setup or the Claude Code option
Claude Code documents a --worktree option: it creates an isolated worktree and starts the session there. See the Claude Code worktree documentation for that entry point.
Use the manual Git commands above when you want an explicit folder and branch assignment that you can give to any terminal session. For example, ../repo-feature-x can host your implementing agent and, later, a separate review session after the writer pauses. Give the reviewer a no-edit instruction if it is inspecting the same working files.
An independent conversation can still share a checkout.
Before starting a second writer, verify its directory even if the terminal title looks correct. The multiple-session guide covers arranging those sessions and deciding how many to keep active.
Review small branches and rebase before merging
Keep one bounded change and one small pull request per worktree. Ask the implementer to finish with changed paths, checks run, and open concerns. Review the actual diff and test output.
A finished agent turn is only the point at which review can begin.
Before merging, stop writers in that worktree and ensure its work is committed and the checkout is clean. If your integration branch is origin/main, update the branch with:
git fetch origin
git rebase origin/mainReplace origin/main with your project's integration branch. Resolve conflicts deliberately and rerun the relevant checks after the rebase. If the branch is already published, coordinate any history update according to your team's policy. Rebase changes commit history; another reviewer should know which revision they are reviewing.
Merge through the project's normal review process, then update remaining branches against the integrated result. When two branches change the same interface, choose an integration order instead of asking both agents to resolve against different assumptions.
Connect the worktree to SpeakCode and clean up
SpeakCode does not manage worktrees. Open one terminal card per worktree directory, label it after the branch, and verify pwd and git branch --show-current before launching the agent. The parallel agents overview describes the surrounding canvas workflow.
For a test handoff, open a second shell in that same worktree's package directory. Connect the agent to it with a belt and choose Run command in the belt inspector, using the project's test command. Configure completion signaling and verify the first handoff with the belt guide. Keep the shell ready: a belt neither starts a stopped terminal nor waits for a busy one.
After review and integration, stop processes using the worktree and preserve any local configuration you still need. From the main checkout, remove it and inspect the remaining registrations:
git worktree remove ../repo-feature-x
git worktree prune
git worktree listRemoval deletes the working directory; it does not delete its branch. Do not force removal to bypass uncommitted work. prune clears stale administrative records for missing worktrees, subject to Git's expiration rules; it does not merge changes.
Skip worktrees when one session is enough
For a 10-line fix with one writer and one test run, a single checkout is often simpler. A read-only review can also use the existing directory while the writer is paused. Separate worktrees become useful when you need simultaneous edits, different branches, or a stable checkout for each task.
Count the setup cost: every worktree needs dependencies, configuration, review, and cleanup. Start with two independent changes. Add another worktree only when its task can progress without waiting for the same unfinished interface.
Questions
Does a worktree isolate ports and databases?
No. Working files are separate, but processes still share the machine and configured services. Assign separate ports and writable resources where needed.
Should I install dependencies in every worktree?
Yes. Follow the project setup instructions in each worktree. Ignored dependencies and environment files are not included in the tracked checkout.
Does git worktree remove delete the branch?
No. It removes the working directory and its worktree registration. Handle branch cleanup separately after confirming the work is integrated.
Can SpeakCode create and remove my worktrees?
No. Manage them with Git yourself, then run each agent terminal and its test shell in the intended worktree directory.