69  69. Git Worktrees and Parallel AI Agents

AI coding agents can work on several tasks at the same time, but not safely in the same folder. Git worktrees give each task its own folder and branch, all connected to one repository. This page shows the Git commands, Claude Code’s built-in worktree support, ways to run several agents at once (including dynamic workflows), and what all this costs you in tokens and attention.

69.1 The problem: one folder, one branch at a time

A project folder has exactly one branch checked out at a time. If two agents (or you and an agent) work in the same folder at once:

  • their edits land in the same files and can overwrite each other;
  • when one of them runs git switch, the files change under the other one;
  • a commit can accidentally include the other task’s half-finished changes;
  • tests run on a mix of both tasks’ code.

You could wait for one task to finish, or make a second clone of the repository. Worktrees are the lighter-weight solution.

69.2 What is a worktree?

A worktree is an extra working folder connected to the same repository. Each worktree has its own files and its own checked-out branch, but all worktrees share one history, one set of branches, and the same remotes. A commit made in one worktree is immediately visible from the others.

projects/
├── git-tutorial-project/             <- branch main       (you)
│   └── .git/                         <- the one shared repository
└── git-tutorial-project-dark-mode/   <- branch dark-mode  (an AI agent)

69.3 Creating and using a worktree

Maria wants an agent to build a dark color scheme while she keeps working on main. From her project folder, she creates a worktree next to it (..) on a new branch (-b dark-mode):

git worktree add ../git-tutorial-project-dark-mode -b dark-mode
git worktree list

Output:

Preparing worktree (new branch 'dark-mode')
HEAD is now at 8cf4abd Merge pull request #2 from maria-lopez/add-projects-page
/Users/maria/projects/git-tutorial-project            8cf4abd [main]
/Users/maria/projects/git-tutorial-project-dark-mode  8cf4abd [dark-mode]

(To use a branch that already exists, leave out -b: git worktree add ../git-tutorial-project-fix fix-typo.)

The new folder behaves like a normal project folder:

cd ../git-tutorial-project-dark-mode
git status
ls -a

Output:

On branch dark-mode
nothing to commit, working tree clean
.  ..  .env.example  .git  .gitignore  README.md  css  src

Notice what is missing: Maria’s .env file. A new worktree contains only the files Git tracks, so ignored files (.env, logs) and installed packages (such as a node_modules folder) are not there. Copy .env over and install dependencies in each new worktree.

Work in the worktree is normal Git work. The agent (or Maria) edits css/style.css there, commits “Add dark color scheme”, and pushes the branch with git push -u origin dark-mode. Back in her main folder, Maria can see the new commit right away, because both folders share one repository:

cd ../git-tutorial-project
git log --oneline --graph --all -3

Output:

* 06b7154 (origin/dark-mode, dark-mode) Add dark color scheme
*   8cf4abd (HEAD -> main, origin/main) Merge pull request #2 from maria-lopez/add-projects-page
|\
| * d38fddc Clarify project name

(-3 shows only the three newest commits.) One rule: a branch can be checked out in only one worktree at a time. If Maria runs git switch dark-mode in her main folder, Git refuses with a message saying dark-mode is already used by the worktree at .../git-tutorial-project-dark-mode. To work on that branch, she uses that folder.

69.4 Removing a worktree

When the task is done, remove the worktree from the main folder:

git worktree remove ../git-tutorial-project-dark-mode
git branch

Output:

  dark-mode
* main

Removing a worktree deletes the folder, not the branch: dark-mode and its commits are still there, ready for a pull request (Pull Requests and Code Review). If the folder still has uncommitted or untracked files, git worktree remove refuses and suggests --force, which would delete those files. If you deleted a worktree’s folder by hand, run git worktree prune to make Git forget it.

Switch branches in one folder A second clone A worktree
Separate folder for each task No Yes Yes
Tasks can run at the same time No Yes Yes
History and branches One repository Two separate repositories; sync through GitHub One shared repository; commits visible everywhere at once
Disk space Least Full copy of history Only the files (history is shared)

In a linked worktree, .git is a small file that points to the main repository’s .git folder, which is why history is shared.

69.5 Claude Code’s built-in worktrees

As of Oct 6, 2026 · Official docs: Run parallel sessions with worktrees · Common workflows

Claude Code can create the worktree for you. In your project folder, run:

claude --worktree dark-mode

(-w is the short form.) Claude Code creates a worktree in .claude/worktrees/dark-mode/ inside your repository, on a new branch named worktree-dark-mode, and starts the session there. Run the same command with a different name in a second terminal to start a second, isolated session. If you leave out the name, Claude Code makes one up. Good to know:

  • Setup. The repository needs at least one commit, and you should have run plain claude in the folder once to accept the folder-trust prompt. Add .claude/worktrees/ to your .gitignore, or the worktrees show up as untracked files in your main folder.
  • Starting point. By default the new branch starts from the repository’s default branch as it is on GitHub (usually main), not from the branch you are on. The worktree.baseRef setting can change this.
  • Ignored files. List files such as .env in a .worktreeinclude file at the project root (same pattern syntax as .gitignore), and Claude Code copies them into each new worktree. Dependencies still need installing; you can ask Claude to do it.
  • When you exit. If the worktree has no changes, Claude Code removes it (for an unnamed session) or asks you. If it has changes, Claude asks whether to keep or remove it; to come back later, run the claude --worktree <name> --resume command it prints.
  • Other ways in. You can ask Claude to “work in a worktree” in the middle of a session; claude --worktree "#2" creates a worktree from pull request 2 (quote it, because # starts a comment in Bash); and the desktop app has a worktree option for each new session.

69.6 Running several agents at once

As of Oct 6, 2026 · Official docs: Run agents in parallel · Manage multiple agents with agent view · Commands

Claude Code offers several ways to run work in parallel. Worktrees keep their file edits apart:

Approach What it is How edits are kept apart
Several terminals, each claude --worktree NAME You start and steer each session yourself Each session has its own worktree
Agent view (claude agents) One screen to dispatch and watch background sessions (research preview) Each session moves into its own worktree before it edits files
Subagents Helpers inside one session (see Subagents) Optional: isolation: worktree
/batch <instruction> Splits one large change into 5 to 30 units, shows you a plan, then runs one background subagent per unit Each unit gets its own worktree
Dynamic workflows A script Claude writes that runs many subagents (below) Agents can work on isolated copies
Agent teams Experimental and disabled by default No worktrees; split the work by files

A background session in its own worktree commits its work and pushes its branch, and can open a draft pull request; agent view then shows the pull request number on that session’s row.

69.6.1 Dynamic workflows and /workflows

As of Oct 6, 2026 · Official docs: Orchestrate subagents at scale with dynamic workflows

A dynamic workflow is a JavaScript script that Claude writes to run many subagents for one big job, such as auditing every file in a folder or migrating dozens of files. A runtime executes the script in the background while your session stays free. Workflows are available on all paid plans; on Pro you first turn them on in the Dynamic workflows row of /config.

  • Start one by asking for it in your prompt (“use a workflow to …”) or by including the keyword ultracode, for example: use a workflow to migrate every component under src/components/ from JavaScript to TypeScript, working on each file in its own isolated copy. Depending on your permission mode, Claude Code shows the planned phases and asks you to approve the run (in auto mode, only the first time). /deep-research is a workflow that comes built in.
  • Watch it with /workflows: it lists running and finished runs; in a run you can see each phase and agent, press p to pause or resume, x to stop, and s to save the script.
  • Reuse it. A saved workflow goes in .claude/workflows/ (shared with everyone who clones the repository) or ~/.claude/workflows/ (just for you), and runs later as /<name>.
  • Mind the cost. One run can start dozens of agents and use far more tokens than doing the task in conversation. Claude Code shows a Large workflow warning for big runs; try a small slice (one folder) first.

69.7 Bringing the work back together

Parallel work only pays off when you can combine it:

  1. Each task ends as a branch (one per worktree or session).
  2. Review each branch’s changes and test them, exactly as you would review a teammate’s work.
  3. Open a pull request per branch and merge them one at a time (Pull Requests and Code Review).
  4. If two tasks edited the same lines, the second merge conflicts (Merge Conflicts).

The best parallel tasks are independent: different pages, files, or features. Two agents restyling the same CSS file will step on each other no matter how many worktrees you use.

69.8 Costs and attention

As of Oct 6, 2026 · Official docs: Manage multiple agents with agent view: Limitations · Manage costs effectively

  • Tokens multiply. Each session uses your plan’s usage on its own; the agent view docs say ten agents in parallel use your quota roughly ten times as fast as one.
  • Your attention is the bottleneck. Every branch needs reading, testing, and merging. Five unreviewed branches are not five finished features.
  • Start small. Two or three well-defined, independent tasks with a clear way to check the result beat ten vague ones.
  • Clean up. Merge or delete finished branches and remove old worktrees (git worktree list shows them all). Background sessions stop if your computer shuts down, and deleting a session in agent view deletes its worktree, so commit anything you want to keep.

69.9 Key takeaways

  • A worktree is an extra folder with its own branch, sharing one repository (history, branches, remotes) with your main folder.
  • git worktree add ../folder -b branch creates one, git worktree list lists them, and git worktree remove ../folder deletes the folder but keeps the branch.
  • A new worktree has only tracked files: copy .env and install dependencies.
  • claude --worktree NAME starts Claude Code in its own worktree under .claude/worktrees/; agent view, /batch, and dynamic workflows (/workflows) run many agents with worktree isolation.
  • Parallel agents multiply token use and review work; choose independent tasks and bring results back through branches and pull requests.

Practice Questions

Easy

Question 1 · Short answer

What is a Git worktree?

An extra working folder connected to the same repository. It has its own files and its own checked-out branch, but it shares the repository’s history, branches, and remotes with the main folder.

Question 2 · True or false

Every worktree contains its own separate copy of the repository’s history, so a commit made in one worktree can’t be seen from the others until you push it.

False. All worktrees share one repository. A commit made in any worktree is immediately visible from the others (for example with git log --oneline --graph --all), without pushing.

Question 3 · Multiple choice

Which command creates a worktree in the folder ../site-fix on a new branch named fix-nav?

  1. git switch -c fix-nav ../site-fix
  2. git worktree add ../site-fix -b fix-nav
  3. git clone ../site-fix fix-nav
  4. git worktree list ../site-fix fix-nav

b. git worktree add <folder> -b <new-branch> creates the folder and the branch together. git switch (a) changes branches in the current folder, git clone (c) makes a separate repository, and git worktree list (d) only lists worktrees.

Question 4 · Matching

Match each command with what it does.

Command What it does
1. git worktree add ../x -b x A. Make Git forget worktrees whose folders were deleted by hand
2. git worktree list B. Delete a worktree’s folder (the branch stays)
3. git worktree remove ../x C. Create a new folder with a new branch
4. git worktree prune D. Show every worktree, its commit, and its branch

1 → C, 2 → D, 3 → B, 4 → A.

Question 5 · Short answer

Give two problems that can happen when two AI agents work in the same project folder at the same time.

Any two: they edit the same files and overwrite each other’s changes; one agent switches branches and the files change under the other; a commit includes the other agent’s half-finished changes; tests run on a mix of both tasks’ code.

Question 6 · True or false

The same branch can be checked out in two worktrees at the same time.

False. A branch can be checked out in only one worktree at a time. Git refuses with a message that the branch is already used by another worktree.

Medium

Question 7 · Predict the output

Sam’s project is in /c/Users/sam/projects/shop on branch main (commit a1b2c3d). He runs git worktree add ../shop-cart -b new-cart and then git worktree list. Describe what the list shows.

Two lines, one per worktree, each with its folder, its current commit, and its branch in brackets: the main folder (.../shop) at a1b2c3d [main], and the new folder (.../shop-cart) at the same commit a1b2c3d [new-cart], because a new branch starts at the commit you were on.

Question 8 · Scenario

Maria creates a new worktree and starts her app in it, but the app fails because .env (which holds her API key) is missing, even though .env exists in her main folder. Why, and what are two ways to fix it?

A new worktree contains only files that Git tracks, and .env is ignored (it must never be committed), so it isn’t there. She can copy .env into the worktree by hand, or, when Claude Code creates the worktree, list .env in a .worktreeinclude file at the project root so Claude Code copies it automatically. (She also needs to install dependencies in the new folder.)

Question 9 · Write the command

Write the command that starts Claude Code in a new isolated worktree named pricing-page. Where does the worktree go, and which branch is it on?

claude --worktree pricing-page

(or claude -w pricing-page). Claude Code creates it in .claude/worktrees/pricing-page/ inside the repository, on a new branch named worktree-pricing-page, and starts the session there.

Question 10 · Scenario

git worktree remove ../shop-cart fails with a message that the folder “contains modified or untracked files, use –force to delete it”. What does that mean, and what should you do before using --force?

The worktree has changes that were never committed (or new files Git doesn’t track). Removing it would delete them, so Git refuses. First go into the folder, check git status, and commit (and push) anything you want to keep. Use git worktree remove --force only for changes you really want to throw away.

Question 11 · Scenario

In her main folder, Maria runs git switch dark-mode and Git refuses because dark-mode is already used by the worktree at .../git-tutorial-project-dark-mode. Explain the message and give two ways to continue.

A branch can be checked out in only one worktree at a time, and dark-mode is checked out in the other folder. She can (1) simply cd into ../git-tutorial-project-dark-mode and work on the branch there, or (2) remove that worktree (git worktree remove ../git-tutorial-project-dark-mode, after committing its work) and then switch to the branch in her main folder.

Question 12 · True or false

Running git worktree remove deletes the worktree’s branch and all of its commits.

False. It deletes only the folder. The branch and its committed work stay in the repository (and on GitHub, if pushed), ready to be merged or deleted separately.

Question 13 · Multiple choice

What does the /workflows command do in Claude Code?

  1. Lists the GitHub Actions workflow files in .github/workflows/.
  2. Opens a view of running and finished dynamic workflows, where you can watch their phases and agents, pause, stop, or save them.
  3. Creates a new git worktree for every branch.
  4. Shows your recent commits as a graph.

b. /workflows is the progress view for dynamic workflows (p pauses or resumes, x stops, s saves the script). It has nothing to do with GitHub Actions workflow files (a), it doesn’t create worktrees (c), and the commit graph comes from git log --oneline --graph (d).

Question 14 · Short answer

When you dispatch a background session from agent view (claude agents) in a Git repository, how does Claude Code keep its file edits apart from your other sessions, and how do you get its work back?

Before editing files, the session moves into its own worktree under .claude/worktrees/, so parallel sessions write to separate folders and branches. It commits its work and pushes its branch (and can open a draft pull request, shown on its row in agent view). You review the branch or pull request and merge it like any other.

Hard

Question 15 · Scenario

Maria has four tasks: (1) write the text of a new FAQ page, (2) fix a typo in the footer, (3) change all link colors in css/style.css, and (4) redesign the whole layout in css/style.css. She wants to run Claude Code sessions in parallel. Which tasks are good to run in parallel, which are not, and how should she bring the results together?

Tasks 1, 2, and one of the CSS tasks touch different files, so they can run in parallel, each in its own worktree (claude --worktree faq, and so on). Tasks 3 and 4 both rewrite css/style.css, so running them at the same time would cause conflicts; do them one after the other (or combine them into one task). Each task ends as a branch: review and test it, open a pull request, and merge the pull requests one at a time, pulling main in between.

Question 16 · Long answer

A classmate says: “If one agent finishes a feature in an hour, ten agents in parallel will finish ten features in an hour.” Explain why that’s too optimistic.

  • Usage: each session uses tokens on its own; ten parallel agents use your plan’s quota roughly ten times as fast, so you may hit limits (or costs) soon.
  • Review: someone has to read, test, and merge every branch; your attention becomes the bottleneck.
  • Conflicts: features often touch the same files, so later merges conflict and need careful resolution.
  • Quality: vague tasks produce work that must be redone. A few independent, well-defined tasks usually finish sooner than ten loosely defined ones.

Question 17 · Compare

Compare three ways to work on two tasks at once: switching branches in one folder, making a second clone, and adding a worktree.

  • Switching branches: one folder, so only one task’s files exist at a time; tasks can’t run simultaneously.
  • Second clone: a separate folder and a separate repository; tasks can run at once, but commits must travel through GitHub (push and pull) to reach the other copy, and history is stored twice.
  • Worktree: a separate folder with its own branch, sharing one repository; tasks run at once, and commits are visible in every worktree immediately.

Question 18 · Scenario

Two Claude Code sessions ran in separate worktrees. Both changed the same heading in src/index.html, in different ways. Maria merged the first pull request without trouble. What will happen with the second one, and what should she do?

Worktrees kept the edits apart while the sessions were working, but they don’t prevent overlapping changes. The second branch now conflicts with main on the heading line. She (or the session, with her review) brings the latest main into the second branch (pull main, then run git merge main while on the second branch), decides what the heading should say, removes the markers, commits, pushes, and then merges the pull request. In future, she should give parallel sessions tasks that touch different files.

Question 19 · Scenario

Sam is on the Pro plan and wants Claude Code to run a dynamic workflow that converts 40 files from JavaScript to TypeScript. What should he know and do before and during the run?

  • On Pro, dynamic workflows must first be turned on in the Dynamic workflows row of /config.
  • Start it by asking for a workflow (or using the keyword ultracode), and read the planned phases when Claude Code asks him to approve the run.
  • A workflow can start many agents and use far more tokens than a normal conversation, so try it on a small slice (one folder) first.
  • Watch the run with /workflows, where he can pause or stop it.
  • Commit his own work first, then review and test the result like any other branch before merging.

© 2025-2026 Y. Rosenthal. All rights reserved.