Omniscio

OmniscioGuidesClaude Code worktrees

Claude Code worktrees

Claude Code is Anthropic's coding tool, and it can run a session inside its own copy of your project. That copy is a git worktree, and Anthropic put the switch on the command you already type rather than in a separate tool.

This page covers what the flag creates, what the copy shares with your main folder, how it is cleaned up, and where Omniscio's own isolation sits.

Checked against Anthropic's Claude Code 2.1.311 on October 27, 2026. By the Omniscio team. Updated .

What a git worktree is, and the problem it solves

A git worktree is a second checkout of the same repository: its own folder, its own branch, and the same history and remote as the folder you already work in. Anthropic describes it in exactly those terms, a separate working directory that shares the repository history and remote with your main checkout.

Because the history is shared, it is not a copy you reconcile later. It is the same project, seen twice.

The problem it solves is a race. Two sessions in one folder fight over the same files, and the later write wins with no error and no warning, so the earlier change is gone. Claude Code's answer is one worktree per session: different files on a different branch, so the two cannot overwrite each other.

Worktrees are a git feature rather than something Claude Code invented, so everything you know about branches still applies and an ordinary git command can list or remove a copy. Claude Code creates one for you and starts the session inside it.

Start Claude in a worktree

The flag is --worktree, or -w, followed by a name. Run it again with a different name in another terminal for a second isolated session. Our guide to running several Claude Code sessions at once covers the wider two-session setup.

By default the copy goes under .claude/worktrees/<name>/ at the repository root, on a new branch named worktree-<name>. Leave the name off and Claude Code makes one up, like bright-running-fox.

Accept the trust prompt first

There is one gate. An interactive session has to trust the workspace, so run Claude once in that directory and accept the prompt, or the flag exits with an error asking you to. Non-interactive runs with -p skip the trust check.

Anthropic's own tip: add .claude/worktrees/ to your .gitignore, so the copies do not show up as untracked files in your main checkout.

Setting the worktree up

A worktree is a fresh checkout, so nothing you installed is there yet. Ask Claude to install dependencies inside the copy, or run your project's setup command in the worktree folder.

A .worktreeinclude file in your project root carries gitignored files such as .env and .env.local into every new worktree, using .gitignore syntax. Only files that match a pattern and are also gitignored are copied, so a tracked file is never duplicated. It applies to every worktree Claude Code creates with git, subagents' included.

Asking Claude to create one mid-session

You do not have to plan ahead. Ask Claude to work in a worktree and it creates one with the EnterWorktree tool. It can then move to another copy under .claude/worktrees/ by calling the tool with a target path, and the copy it left stays on disk untouched.

One approval rule matters. When Claude enters a path outside the repository's own worktrees folder, Claude Code asks you first, because that move takes the session's working directory, its write access, and project config such as CLAUDE.md and settings with it. A permission rule or "don't ask again" does not suppress that prompt. Only bypass permissions mode skips it.

What the copies share with the main checkout

The copy has its own files and branch. Four things stay shared with the checkout you launched from.

  • The repository's .git directory. Git commands inside a worktree write to the main repository's shared git directory, and Anthropic's sandboxing allows those writes, so a commit works from inside a copy with the sandbox on.
  • Plugins. A project-scope plugin from the main checkout also loads in worktrees of the same repository, so you do not reinstall it per copy. It needs Claude Code 2.1.200 or later.
  • Permission approvals. Saying yes and not being asked again saves the rule to the main checkout's local settings, so it applies there and in every other worktree of the repository, and it survives the copy being removed. On Windows, and wherever Claude Code does not use the repository root, the rule stays with that one copy.
  • Untracked skills, agents and commands. When a copy has no skills folder of its own, for example because yours is gitignored, the main checkout's project skills load into the session. Agents and commands follow the same read-through. A copy with its own skills folder loads only that one.

A gitignored file is in the copy only if .worktreeinclude names it. That is the whole reason the file exists.

How isolation is enforced

While a session is isolated, Claude Code blocks the tool calls that four checks define.

  • An edit that targets a path in the main checkout.
  • A command whose working directory resolves to the main checkout, or cannot be verified as staying outside it.
  • A command that sends git into the main checkout, through git -C, a git directory variable, or a change of folder before the git command.
  • A command whose text does not prove that the git command it runs stays inside the worktree: a name computed while it runs, syntax it cannot parse, or an expansion that could run a command the text does not spell out. Claude is told how to rewrite it, and this check cannot be switched off.

The same rules apply whether you used the flag, the entry tool, or a resumed session, and they cover every subagent that session starts.

What the checks cannot see

The checks read the path an edit targets, the folder a command runs in, and the command's text. None tracks which files a shell command actually writes, so a command that writes into the main checkout without running git there, a plain copy or a shell redirect, is not refused by these checks.

Claude Code treats a command like that as any other shell command, under your own permissions and sandboxing.

They cover the repository you launched from, and the main checkout that copy was linked to. On PowerShell commands, only the working-directory check applies. A refusal reaches Claude as a tool error naming the worktree and saying how to proceed.

Subagents in their own worktree

Subagents can have their own copies too, which keeps their edits from colliding. Ask Claude to use worktrees for its agents, or make it permanent for a custom subagent by adding isolation: worktree to its frontmatter, the settings block at the top of the file.

Claude Code gives each a temporary worktree and removes it when the subagent finishes with no changes; one that does hold changes stays until a later sweep can remove it without losing work.

Subagent copies use the same base branch rule as the flag, so they branch from your repository's default branch unless you have set the base to your current work. And a subagent takes its instruction files from your main conversation, not its own copy, so a rule file that differs on the copy's branch is not what it reads.

Choosing the base branch and customising creation

The defaults suit most sessions: a copy under .claude/worktrees/, branched from the repository's default branch, tracked files only. Five things change that.

  • The base branch. New copies branch from the default branch on the remote, usually main, so the session starts from a clean tree that matches it. worktree.baseRef takes "fresh", the default, or "head", which branches from your local history so the copy carries your unpushed commits and feature state, which is what you want when a subagent works on unfinished work. You cannot name a branch there; for a specific branch, create the copy with git.
  • Branching from a pull request. Pass a pull request or merge request number prefixed with #, or a GitHub or GitLab URL, and Claude Code fetches that change's head commit into .claude/worktrees/pr-<number>. Quote the argument, because a shell reads # as a comment.
  • Copying gitignored files. The .worktreeinclude file above is the switch, and it applies to every copy Claude Code creates with git.
  • Reusing a name. A name whose folder already exists opens that copy instead of making a new one. With the default base it resets to the repository's default branch only when three things hold. It has no uncommitted changes or untracked files. It is still on the branch Claude Code made for it. And it has no commits of its own, or its pull request was merged and its remote branch deleted. Otherwise it opens at its old tip, and a pull request name never resets.
  • Replacing creation with a hook. A creation hook can replace the git step entirely, including putting copies outside the default folder, and a removal hook cleans them up. That is how the feature reaches a project that does not use git.

Resuming a worktree session

Resume a session that ended in a worktree and Claude Code puts it back there, for an interactive resume and for the continue and resume commands in non-interactive mode. Continue picks the most recent session recorded under the folder you launch from. Back inside, Claude can still leave with the exit tool.

Before returning, Claude Code checks the copy is still a separate checkout and declines one that fails.

Where you launch from matters. From the main checkout, or another folder of the repository, a git-made copy is re-entered even if you launched inside it. From inside another worktree, it re-enters only when it can vouch for that copy from there, so those are best started from the main checkout.

If the folder is gone, it resumes where you launched, says the copy no longer exists, and clears the binding. A fork starts where you launched and leaves the original copy untouched.

Cleaning up, and the safeguards before anything is deleted

Leaving an interactive worktree session is not just an exit. For a git-made copy, Claude Code looks for work that removing it would destroy: changed or untracked files, uncommitted work inside a checked-out submodule, and new commits. What it asks depends on what it finds.

  • The copy is clean. An unnamed session loses the copy and its branch without asking. A named one is asked first, so you can keep it.
  • The copy has work in it. You are asked to keep it or remove it. Keeping preserves the folder and branch and prints the resume command. Removing deletes the folder, the branch and the work.
  • Another branch is checked out in it. When the copy sits on another branch with commits past the copy's start, you are asked to keep or remove. Either answer keeps that branch and its commits. Removing deletes the folder and the branch Claude Code made.
  • The copy's state cannot be verified. When it cannot count changes or inspect the submodule checkouts, it asks rather than removing anything, and names what it could not check.

A non-interactive run has no exit prompt, so it does not clean up: the lock taken at creation stays until a later session's sweep releases it.

To remove one by hand, run git's remove command, releasing the copy's lock first if git refuses because it is locked. On Windows, removing a copy never deletes anything outside it: an inner folder that is a link loses only the link, and its target is kept.

When a worktree will not work

Anthropic lists the failures and what each one means. These are the ones worth recognising.

  • Claude Code cannot enter the copy at startup. It names the path and exits with code 1. Usually a hook printed something other than the folder it created, or the folder was deleted after setup. Recreate it, and fix the hook if there is one.
  • Creation fails on a symlinked path. When the configuration folder, the worktrees folder, or the copy's own folder is a symbolic link, the error names the link. Remove the link and retry.
  • Git LFS files are pointer files. If large-file storage was set up locally for the repository, a copy holds pointer files instead of the real ones. Run the LFS pull command inside the copy to fetch them. Claude Code skips a repository's own filter drivers, which is what leaves the pointers behind.
  • Creation fails in a partial clone. Some objects the starting commit needs could not be fetched. Take the step the message names, then run the flag again from that same shell.
  • It refuses to use a copy. An error beginning "refusing to use a path" means the folder's git identity was checked and declined. The rest of the message says which case you are in.
  • Launch from the parent checkout: you launched from inside the copy, and the copy needs no recreation.
  • Cannot be resumed or re-entered: nothing vouches for it from where you launched. Recreate it and recover what you need from the old folder, which stays on disk.
  • Contains the protected checkout: that folder is a parent of your main checkout. Do not delete it; change the copy's path instead.
  • The main checkout's git metadata: the copy is fine, and the main checkout is what needs repairing.
  • A network spelling in the recorded path: Claude Code never resumes into a copy at a network path, so recreate it somewhere local.
  • The session resumes outside its worktree. The commonest message is that the copy no longer exists: the session continues where you launched, the binding is cleared, and nothing needs doing. The other is that the copy could not be verified this time, which is usually short-lived: the binding is kept, the session continues without isolation, and resuming again retries it.

Where Omniscio fits

Omniscio has the same idea, called session isolation. It gives a session its own copy of your project, a git worktree on its own branch, in a <your-project>-worktrees folder beside the project folder rather than inside it, so your repository stays clean and searches across it stay quick.

Isolation is off by default, with one exception covered further down: nothing hands a session its own copy on its own, and a session that has already started stays where it is, because isolation is chosen before it begins.

Four places to turn it on

  • Shift+click the plus button in the Sessions panel, which starts that one session in its own copy.
  • Open the ⋯ menu on a session that has not started yet and switch Worktree Session on or off for that one session.
  • Edit Project, then More options, then Isolate new sessions, for every new session in that project.
  • Settings, then Sessions, then Work on separate copies, for the app-wide default.

All four ship off, and your choice applies to sessions you start next, not the ones already running.

One exception: a session on an engine whose tools run outside Claude Code's guardrail hooks is isolated by default, because for those engines the copy is the only structural barrier between the agent and your real checkout. In this build that is Gemini, Grok, Antigravity, OpenCode, Hermes, Pi, Kimi Code and DeepSeek Harness.

The project and app-wide defaults cannot turn that off; a per-session choice can, and a project that is not a git repository always runs in place. Everywhere else, isolation stays off by default.

What a copy holds

A copy holds your tracked files, the files git already follows, on a new branch for that session, plus your .env files from the project root, carried across because the agent needs them and git does not move them. Anything git does not track is absent: a scratch file, build output, an uncommitted config.

Dependencies are prepared in the background once the folder appears, so for the first moments a large project may not have its installed packages yet and the agent's first build or test can need to wait.

The branch, and landing it later

Work is committed on the session's own branch. When the session is archived, Omniscio can merge that branch back into your project, but only while the automatic merge-back is switched on. It is off in a fresh install, so a default install merges nothing and keeps the branch with every commit on it.

If the branch conflicts, Omniscio can start a short resolver session to settle it before it lands. The resolver is a real session, billed like any other, so a conflicting archive spends a little of your account's usage. It runs only as part of that merge-back, and never while the merge-back is off.

A kept branch is named session/<session-id>-<slug>, and it outlives the copy's folder. You can merge it with your usual git commands, or switch the automatic merge-back on and let Omniscio land it.

How copies are cleaned up

Copies are reclaimed on rules that check before they act. A copy whose branch is proven merged into your project is removed within minutes. A session left untouched for six hours hands its copy to a reuse pool while the branch keeps every commit, and gets a fresh copy the next time it runs.

To keep a copy for good, put free text in the copy's branch description asking for it to be kept, such as a note saying not to delete this worktree, stops every cleanup lane from removing it. The same words in the folder name work just as well.

Before a copy whose work has already landed is removed, anything it holds that git ignores, such as a scratch file or a saved report, is moved into Omniscio's rescue folder rather than deleted with the folder.

Isolation costs disk: each copy is a real checkout with its own branch and dependencies, so two isolated sessions on one large project take roughly two checkouts' worth of space. That is the trade for two sessions not fighting over one folder.

Omniscio is a desktop app for running Claude Code and other agent harnesses side by side. Any model, any harness — Claude Code, Codex, OpenCode, Devin, Pi, and Hermes all supported. The Free plan covers 8 projects, and Pro is $20/month or $192/year.

One boundary: the per-session spend cap applies only to sessions billed to a pay-per-use API key, and never to a Claude Pro or Max subscription.

Omniscio's isolation is one route to a working copy, not the only one. If you would rather set the copies up yourself, in a terminal, our guide to running several Claude Code sessions at once walks through the git commands in order.

How we tested this

Everything here about Claude Code was read from Anthropic's documentation in its Markdown form on October 27, 2026, and the version line comes from this machine: claude --version answered 2.1.311 (Claude Code) that day. No worktree was created here to write this page, so the folder, branch and cleanup behaviour is Anthropic's account rather than a run of our own.

Everything about Omniscio's isolation comes from our own library, verified against the application's source. Where the two disagree, Anthropic is right, because this part of Claude Code changes on nearly every release.

Sources

  • Anthropic's Run parallel sessions with worktrees, for the flag, the folder and branch it creates, the workspace trust gate, the include file, the entry tool and its approval prompt, the four isolation checks, what a copy shares with the main checkout, the base branch and the other creation options, resuming, the cleanup outcomes and the troubleshooting list.
  • Omniscio's library page Session isolation, for where the switches live, what a copy contains, the merge-back and the branch name, and the cleanup rules.

Common questions

Are worktrees on by default?

No. Anthropic's Claude Code creates one only when you pass the flag, or ask Claude to work in one during a session. Omniscio's isolation is off by default too, and it is switched on for one session, one project or the whole app. Its one exception is an engine whose tools run outside Claude Code's guardrail hooks — Gemini, Grok, Antigravity, OpenCode, Hermes, Pi, Kimi Code and DeepSeek Harness in this build — where a session in a git repository is isolated by default, because the copy is then the only structural barrier between the agent and your real checkout. The project and app-wide defaults cannot turn that off, and an explicit choice for one session can.

Can two sessions edit the same file safely?

Only if they are in different copies. Two sessions in one folder write over each other without an error, which is the race a worktree exists to prevent. With each session in its own copy, Anthropic's Claude Code puts the edits on separate branches instead of on top of one another.

Does the copy include ignored files such as .env?

A worktree holds tracked files, so an ignored file is absent until a .worktreeinclude file in your project root names it. Omniscio is more generous by default: it copies your .env files into an isolated session without being asked, while leaving everything else git ignores behind.

What happens to the branch when a session ends?

It depends on what the exit check finds. Anthropic's Claude Code removes the copy and its branch only when there is nothing there to lose, and asks you in every other case. A named session is asked before a clean copy goes, so you can keep it for later. Omniscio keeps the branch and names it after the session, merging it back into your project only while the automatic merge-back is switched on, and it is switched off in a fresh install, so a default install keeps the branch.

Does a worktree use extra disk?

Yes. A copy is a real checkout with its own branch, and once its dependencies are installed it holds its own installed packages as well, so several copies cost several times what one folder costs. Omniscio's isolated sessions carry the same cost, in exchange for your project folder being left alone while an agent works.

Can I use worktrees without git?

Not with the defaults. Anthropic's worktree feature is built on git, so a project kept in SVN, Perforce or Mercurial needs a creation hook to replace the git step and a removal hook to clean up after it. In Omniscio, a folder that is not a git repository always runs in place, with no copy at all.

Give every session its own copy

Omniscio can put each session in its own copy of your project, keep the work on its own branch, and land that branch for you once the automatic merge-back is switched on. The features page covers what else it does, and you can download it for Windows, macOS or Linux.