A worktree session runs Claude in its own git worktree: a second working
directory of the same repository, on its own branch. Several sessions can then
work on one repository at once without editing the same files, switching each
other's branch, or mixing their changes in one git status.
- For one session:
+→ Claude (Configure...), turn Worktree on, and optionally type a name. - For every new session: the Worktree and Worktree Name settings, in
Global or Project Settings. Claude in the
+menu then starts worktree sessions directly.
Switchboard passes --worktree, followed by the name when one is given, to
claude. The CLI creates the worktree and its branch, and runs the session in
it; without a name, the CLI picks one. The worktree lands at
<repository>/.claude/worktrees/<name>/.
The option applies to every launch that starts a session rather than resuming one:
- a new session;
- a fork: with Worktree on in the effective settings, the command is
claude --resume <id> --fork-session --worktree [name], so the fork runs in a new worktree; - a row whose transcript was never written, which is started with
--session-idrather than resumed.
It is ignored on a plain resume, which keeps the directory the session already
runs in. It is also
dropped, with a warning in the main log, when the project directory is not
inside a git repository: claude refuses --worktree outside one, and the
session starts in the project directory instead.
A Worktree Name saved in the settings is passed to every new session; leave
it empty (placeholder auto) to let the CLI name each worktree.
- Sidebar. A Claude worktree session's transcript is stored by the CLI under the
worktree's own encoded path in
~/.claude/projects/. Switchboard maps any directory of the form<repo>/.claude/worktrees/<name>,<repo>/.claude-worktrees/<name>,<repo>/.worktrees/<name>or<repo>/.work-files/worktrees/<name>back to<repo>when<repo>exists — whether the worktree still does or not — so the session is listed in the repository's project, beside the sessions run in the repository itself. Codex rollouts use their recorded cwd for the same grouping. Nested layouts collapse repeatedly while each parent exists. Layout names are matched without case sensitivity on Windows only. - Resume and fork run in the directory recorded in the session's
transcript — the worktree — because
claude --resumelooks the session up by directory and would not find it from the repository root. Codex also keeps its recorded worktree cwd for resume and fork. If that directory was deleted, Switchboard refuses the launch and names the missing worktree. - The Changes panel and the Shell panel read and run in the worktree too — see Changes view and Terminal.
- In the sandbox, a resumed worktree session also gets the repository root bound read-write, because the worktree's git metadata lives there; the repository's config and hooks stay read-only (What the sandbox protects).
Deleting the parent project from its header or Project Settings keeps linked
worktree histories and offers a separate checkbox for each registered linked
worktree folder. Each choice starts unchecked every time. The preview names the
full path, branch, dirty/untracked files and sessions. The main checkout and the
selected project directory cannot be removed. Unselected folders and branches
are kept. Selecting a folder removes its contents, including ignored files,
memory, schedules or .work-files stored inside it; their contents are not backed up.
Stop linked-worktree sessions before selecting their folders. Unknown activity
and background job records refuse removal; background jobs remain unsupported
even when reported done. Locked worktrees and submodules require the dedicated
worktree dialog below. Remote disk removal is unavailable. Directory links use
the same guards as the dedicated dialog: remove a node_modules junction with
rmdir <path> without recursive deletion, then reopen the preview.
After the parent project's sessions stop, selected folders are removed one at a time before the project's app metadata is changed. A changed preview requires fresh confirmation. A failed removal stops the sequence and lists removed, failed and remaining paths in a persistent notice. Review disk and Git registration, then choose Review remaining deletion for fresh consent. There is no rollback or automatic replay. After restarting the app, previous disk outcomes may be unknown: a new preview inspects the remaining registration and folders; a metadata receipt alone does not prove disk removal succeeded.
When the work is merged or abandoned, remove the worktree from Switchboard or with git.
From Switchboard. A worktree the sidebar shows as a nested header, under
its repository, has a delete button in that header (Delete worktree from
disk).
Before opening the dialog, Switchboard checks that the path uses a recognized
worktree layout and its parent repository is a known project. A refusal appears
in a notice, without a confirmation. These checks run again when deleting.
The dialog shows the full folder path (your home as ~, the absolute path on
hover), branch, and local running sessions whose working directory is inside
the worktree, including open terminals and live sessions outside this window.
It warns that uncommitted changes are lost and lists their paths, ten at most.
When ignored entries exist, it counts them and warns that they are deleted too;
an ignored directory such as node_modules counts as one entry, not each file.
Delete worktree rechecks Git's status, staged contents and the contents of
every changed or untracked file against the preview. Untracked files are listed
individually even if your Git configuration normally hides them. A clean
worktree without submodules or a lock is removed without force. Dirty files
permit force only while their paths and contents still match the preview.
Ignored files (including an edited .env) and ignored directory contents are
not compared; edits to them are deleted without another review. Ignored
directories are not expanded in the dialog. A changed snapshot or a Git refusal leaves
a persistent notice and reopens the dialog with the fresh status, requiring
another confirmation. A locked worktree shows its lock reason and requires
checking Delete this locked worktree, overriding its lock before deletion;
there is no automatic double-force retry. Worktrees containing submodules also
require checking Delete this worktree and its submodules with force;
changes inside initialised submodules are rechecked too. A nonempty uninitialised
submodule directory refuses deletion and asks you to review or move its files;
it is not read as though it were the parent repository. The branch is kept. The
worktree's sessions move under the repository's header, at once or at the
next refresh, since their transcripts are still on disk. Deleting a
finished background session in the Agents view delegates
to claude rm <job> without any force option; Switchboard does not retry it
with force. Both surfaces require fresh checks and never silently escalate a
refusal into forced removal. The sidebar's remote worktree headers share the
local button code, but cannot use the local deletion backend: their notice
directs you to review and remove the worktree with git on its host.
Registration is matched by the on-disk path of the parent folder; a worktree path that is itself a link, or the main checkout, is refused.
On Windows, preview and deletion refuse every directory link, including
junctions and directory symlinks whose targets are inside the worktree. Git for
Windows can follow junctions during removal and leave a partly deleted folder
after unregistering the worktree. On POSIX, links resolving inside the worktree
are allowed; outside or unresolved directory links are refused. These rules
also cover ignored folders. Self-resolving reparse directories are walked as
ordinary directories. The refusal names up to
ten unsafe links and gives the total count. Remove each unsafe link first: for a Windows
junction use rmdir <path> without recursive deletion; on POSIX use rm <link>
without -r. Then retry Delete. Each link scan has a 200,000-directory limit
and a five-second budget; exceeding either refuses with instructions to review
or reduce the tree. Preview scans once; Delete checks the fresh status and then
scans once more immediately before asking Git to remove the folder. There is a
known race after that last scan: filesystem changes, including a newly created
or retargeted directory link, can occur before or during Git's removal. These
checks do not lock the filesystem or make removal atomic.
A preview above 512 MiB of total hashed data
refuses with instructions to review or move the largest files it encountered.
If removal is interrupted, its notice warns that the folder may be partly
deleted: review the remaining folder and Git registration before retrying.
If Git refuses removal and a fresh preview fails, the notice preserves Git's
error and warns that registration may be gone and the folder partly deleted.
With git, from the repository:
git worktree list
git worktree remove .claude/worktrees/<name> # refuses if it has uncommitted changes
git branch -d <branch> # the branch stays after the worktree goes
git worktree prune # after deleting a worktree directory by handEither way, the sessions' transcripts are the CLI's and are not deleted. Once its worktree is gone, a session is resumed from the repository root, where the CLI does not find it; delete or archive it.
Add .claude/worktrees/ to the repository's .gitignore, or the worktrees
show up as untracked files in the main working tree.