Worktree isolation for agents that write the same files

Worktrees in Claude Code

The support for git worktrees in Claude Code is accessible via the --worktree flag, you can also shorten it to -w, and you can provide it with an optional name as follows:

claude --worktree feature-auth

Based on the docs, we checked it in our local repository. The layout is as follows: the worktree lands under .claude/worktrees/<name>/ at your repository root, on a new branch named worktree-<name>. If you do not provide the name, it will automatically generate a three-word label like bright-running-fox. So before using it for the first time, make sure to add .claude/worktrees/ to your .gitignore file.

In terms of how it works behind the scenes, for every custom subagent that you define in .claude/agents/ directory and mark there as isolated with an isolation: worktree key inside frontmatter, Claude Code creates a separate checkout during the run of such a subagent. Here's an example of how it could look for a refactoring subagent:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

You can also tell Claude Code to use worktrees for agents during an ongoing session — the docs' own phrasing for it is to ask Claude to "use worktrees for your agents".

And in terms of the cleanup process, it's all handled automatically and with a bias towards safety:

• if there are no changes in the subagent's worktree, it gets removed once the subagent is done

• otherwise, the worktree is kept so that the next scheduled sweep won't remove it before the changes get committed

So generally speaking, the sweep ignores any worktrees containing modified or untracked files or with commits not pushed yet, and it also doesn't touch worktrees created via --worktree flag.

There are two additional options you can set that define how the fan-out will be arranged:

• worktree.baseRef (set to "fresh" by default) — decides what's the base of the fan-out, "fresh" is pointing to the remote default branch, and "head" to the local HEAD, the latter is useful if you want your agents to work on changes you haven't commited yet

  JSONCopy

  {
    "worktree": {
      "baseRef": "head"
    }
  }

• .worktreeinclude (located at project root level) — copies the gitignored paths you list in it into every worktree Claude Code creates, "uses .gitignore syntax", and copies "only files that match a pattern and are also gitignored" so it doesn't duplicate any tracked files

We checked that one the direct way: put .env in a .worktreeinclude, ran a headless session with --worktree, and the file was there in the new checkout with its contents intact.

Gotcha: the documentation states that using -p flag causes the run to not clean up after itself so the worktree will remain locked. If you try to remove it with git after such a run, you won't be able to because of the lock:

$ git worktree remove .claude/worktrees/wt-run
fatal: cannot remove a locked working tree, lock reason: claude session wt-run
(pid 51507 start Mon Aug  3 16:58:55 2026)
use 'remove -f -f' to override or unlock first

The error message will include information what is the reason for the lock including the session name, PID and start time. So in such scenarios, make sure to unlock first and then remove it. But also as a bonus, thanks to the reason for the lock containing the session and PID, you can combine git worktree list with ps to see which worktrees belong to your agents currently working on something and which are leftovers from previous scripted runs.

Worktrees in Codex CLI

Codex supports worktrees, but not in the CLI tool; the docs say "Worktrees are available only in Codex in the ChatGPT desktop app."

We checked and neither codex nor codex exec have a --worktree flag, for example (both version 0.146.0). So what the desktop app does is still relevant, as it has 2 habits that we could aim to emulate given the CLI doesn't implement any of these:

• It creates worktrees under $CODEX_HOME/worktrees

• It has a .worktreeinclude file listing the ignored paths to copy into new worktrees it manages (same as Claude Code). Also, it "automatically copies an ignored AGENTS.override.md into local managed worktrees", without even asking about it.

But we've found one limit here — "a branch represents a single mutable reference", so a branch created in a worktree "can't be checked out in any other worktree, including your local checkout at the same time."

So we would need to implement it by hand. It's -C, --cd <DIR>, which runs the entire session in a different directory. We could for example create a new branch and worktree there at HEAD, copy the env file there, and then run codex exec -C <path-to-the-worktree>:

git worktree add -b agent/auth .worktrees/auth "$(git rev-parse HEAD)"
cp .env .worktrees/auth/.env
codex exec -C .worktrees/auth "Harden src/auth.ts and commit"

Contrary to --add-dir <DIR>, which declares "additional directories that should be writable alongside the primary workspace", so it does the opposite of what we need — you aim to restrict access with a worktree, not to allow more access. You could combine -C with --ephemeral, which runs "without persisting session files to disk", if you want to do some work in multiple runs but never come back to these.

Gotcha: we wouldn't recommend fanning out your own agents if it comes to writing, even within a session, as it will just create new threads and there's no way of assigning them to their own directories from there — they all share one working tree, which is the "losing changes" setup. You can track an issue in the OpenAI repo about allowing spawn_agent to create sub-agents in a separate workspace or worktree directory, it's 23095, but still open. Until that's done, if you want to do some heavy writing we'd suggest creating a script that runs codex exec -C for each worktree from the command line.

Worktrees in GitHub Copilot CLI

The Copilot CLI doesn't have support for git worktrees. We checked it by using the copilot --help command on 1.0.77 and by examining GitHub's fleet mode documentation and didn't find any information about worktrees, shared filesystems or locking there. What it has instead is /fleet, which is a group of subagents running in parallel that have, in GitHub's words, "its own context window, separate from the main agent and other subagents". But if you have a look at the docs and the help output, neither of them mentions anywhere that these subagents are in a different directory, so going by what's documented they all operate under the working directory from which the command is invoked.

It also documents best practices for usage scenarios that assume 1:1 ratio, like "Multi-file refactors where each worker owns a file, package, or language SDK" or "Batch reviews where each worker checks a separate diff, module, or alert group". The only thing it warns about in terms of the fleet mode is not to create a scenario in which multiple workers operate on the same files — its avoid-list names "Tightly coupled edits where workers would contend for the same files" — but it's the responsibility of the user to make sure they don't do it (the docs literally say: "Avoid assigning overlapping files to different workers unless the parent agent will reconcile conflicts explicitly.").

This means that it's up to the orchestrator, not you, to decide how to split things and the tool doesn't enforce anything in this regard. If you want to have a parallelised write-heavy process, we'd recommend avoiding using /fleet during the session and instead invoking multiple instances of the CLI with a separate checkout per invocation by using the -C <directory> option, which the help text describes as "Change working directory before doing anything else". You could for example set up a shell script that creates a branch and a worktree per target file, copies .env in place, starts the Copilot processes in the background and waits for them to end.

for f in src/auth.ts src/billing.ts; do
  slug=$(basename "$f" .ts)
  git worktree add -b agent/"$slug" .worktrees/"$slug" "$(git rev-parse HEAD)"
  cp .env .worktrees/"$slug"/.env
  copilot -C .worktrees/"$slug" -p "Harden $f, then commit" &
done
wait

In such scenario, you don't have the .worktreeinclude file or setup hook, so it's your responsibility to include the config by copying it manually as part of the process. If you'd rather go for a read-heavy scenario, you can just use /fleet for reviews and research or cross-module triage (in which case you can't destroy anything anyway).

Gotcha: the headless Copilot runs need the proper tool permissions to be set up beforehand (the most permissive option being --allow-all-tools) so if you were to launch a fan-out this way, all of your worktrees will run with all the tools unlocked simultaneously. It's better to specify only the required tools using --allow-tool and --deny-tool. The worktree isolation only protects other agents from this one, it doesn't protect you from any of them.

Worktrees in Cursor

Of the six harnesses, cursor-agent is the most well-featured one when it comes to worktrees. Its --help shows three flags for them: --worktree, --worktree-base and --skip-worktree-setup.

-w, --worktree [name]        Start in an isolated git worktree at
                             ~/.cursor/worktrees/<reponame>/<name>. If
                             omitted, a name is generated.
--worktree-base <branch>     Branch or ref to base the new worktree on
                             (default: current HEAD)
--skip-worktree-setup        Skip running worktree setup scripts from
                             .cursor/worktrees.json (default: false)

The first one creates isolated worktree with an optional name (it'll be automatically generated if not provided) under ~/.cursor/worktrees/<reponame>/<name>. The base is the branch or ref to use for this worktree, defaulting to the current HEAD. And the last flag is about ignoring setup scripts defined in the .cursor/worktrees.json file, by default they are being executed during worktree's creation.

By the way, the base is important because cursor-agent uses HEAD as a default value, which means that if you run it without --worktree-base it starts from whatever commits you have locally (including unpushed ones). Usually, it's what you want, but be mindful it's the opposite of what some other dev harnesses do by default, so it might be worth considering when migrating between them.

The main feature is a setup script defined in .cursor/worktrees.json under the key setup-worktree-unix (or setup-worktree-windows) or setup-worktree if you want to have a fallback for the other system. The value should be either an array of shell commands or path to a file with a script. You can use $ROOT_WORKTREE_PATH variable there pointing to the main checkout. For example:

{
  "setup-worktree": [
    "pnpm install",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

It installs dependencies using pnpm and copies .env from the root checkout. We ran it: the CLI printed a worktree setup panel and "Worktree setup complete.", the .env copy landed, and the marker file our script wrote was there too. The worktree itself was under ~/.cursor/worktrees/<reponame>/<name>, and on a branch called the same as the worktree (without any prefix). The agent automatically removes old worktrees periodically, the interval for that is defined by cursor.worktreeCleanupIntervalHours (defaults to 6h), and cursor.worktreeMaxCount limits it to 25 per machine. The IDE has this feature too, in form of skills: /worktree — continue chatting in another checkout; /best-of-n — run the same task for a few models, in separate worktrees.

Keep in mind though that the docs recommend against symlinking dependencies into the worktree — "We do not recommend symlinking dependencies into the worktree. This can cause issues in the main worktree" — so think twice before writing your setup script.

Gotcha, and we hit it on the first run: the worktree is created before the trust check. In a directory Cursor hadn't been trusted in, the run stopped with "To proceed, you can either: Run 'agent' interactively to decide / Pass --trust, --yolo, or -f if you trust this directory" — and the worktree was already on disk, empty of any agent work. Trust the workspace first (or accept the prompt interactively), or your fan-out leaves a trail of abandoned checkouts to reap.

Worktrees in Gemini CLI

Gemini has a gemini -w or --worktree flag (it is marked as experimental and bound to the feature flag), when this feature is disabled it refuses to create a worktree with an informative message but doesn't ask LLM for anything or create any worktrees:

$ gemini -w gem-test -p "Reply ok"
The --worktree flag is only available when experimental.worktrees is enabled in your settings.

The feature can be enabled by setting the experimental.worktrees to true in the settings:

{
  "experimental": {
    "worktrees": true
  }
}

If it's enabled, then gemini --worktree feature-search creates .gemini/worktrees/feature-search in the repository.

The cleanup is on a user — "When you exit a worktree session (using /quit or Ctrl+C), Gemini leaves the worktree intact so your work is not lost" — so the worktrees are preserved until you remove them, and to remove them you can run:

git worktree remove .gemini/worktrees/feature-search --force
git branch -D worktree-feature-search

And you need to initialise dev environment in each new worktree: "Remember to initialize your development environment in each new worktree according to your project's setup."

We reckon Google's warning about parallel subagents is the case for turning this feature on: "Exercise caution with parallel subagents for tasks that require heavy code edits. Multiple agents editing code at the same time can lead to conflicts and agents overwriting one another."

Antigravity has no equivalent of this, you can only do agy --add-dir or --project, there's no agy -w there (for example on 1.1.9, agy --help says nothing about worktrees), so the way to work with it is to create worktrees with git and run a separate instance of the CLI in each dir.

Gotcha: we've also found that for example on 0.46.0, setting experimental.worktrees to true in the project's settings file doesn't enable the feature — even with this set to true it still refuses to create a worktree; tried both with and without --skip-trust. So we'd say to rather set it in user's settings as for example if someone clones your repo they might not be able to use it with this set to true in the project settings.

Worktrees in Kimi Code CLI

In the Kimi Code CLI there's no support for worktrees. When you run kimi --help on version 0.31.1 it doesn't list any flag for it, and the Moonshot sub-agent docs are silent about worktrees as well as per-sub-agent working directories (they only describe isolation based on the context window). There's no mechanism to assign a sub-agent its own directory in either the docs or the CLI.

Let's take a closer look at this part of the docs:

"Multiple sub-agents can run in parallel without interfering with each other."

The next paragraph defines what isolation means — that for a sub-agent it's about having its own separate context window (it only sees the task description given by the main agent, not the main agent's entire conversation history), so from that perspective the non-interference between multiple sub-agents is about the main agent's conversation history; if you were to run three coder sub-agents on a single file they would collide exactly like three shell scripts would.

There's also no flag like -C that would change the current directory in the style of cd, so what's left is --add-dir <dir> which defines an extra workspace directory, but doesn't change the session's current directory. What it means is that with Kimi Code you achieve isolation by using cd and launching a separate process per worktree. This for example is how you could create a worktree and a branch for every file, copy .env there and start an instance of kimi in the background for each worktree:

for f in src/auth.ts src/billing.ts; do
  slug=$(basename "$f" .ts)
  git worktree add -b agent/"$slug" .worktrees/"$slug" "$(git rev-parse HEAD)"
  cp .env .worktrees/"$slug"/.env
  (cd .worktrees/"$slug" && kimi -p "Harden $f, then commit" --output-format stream-json) &
done
wait

If you have slices that require different profiles (like some for read access and others for write access), you can use --agent <name> flag to pass a specific sub-agent per run, for example using explore for read-only slices and coder for the ones that need writing, so it's only the latter ones that require worktrees.

Gotcha, and it's the useful kind: if fan-out of sub-agents doesn't work as intended, it's possible to inspect what went wrong. The runtime state of sub-agents is saved in the agents/ subdirectory of the current session directory, with a separate directory per instance, and each of these directories contains wire.jsonl file which keeps chronologically-ordered prompts, messages history and the final state, so that's where you can find out if two sub-agents operated on the same file. The thing is that they don't raise an error in such scenarios, so it won't be visible from the transcript.