--worktree
A Claude Code CLI flag, read out of the shipped bundle. It has been in the build since v2.1.138, including the newest one read.
Also written -w. Every list on this page counts all of these spellings together.
Start Claude in an isolated git worktree at <repo>/.claude/worktrees/<name>. If you don't give a name, Claude Code generates one. Pass #<number>, a GitHub pull request URL, or a GitLab merge request URL to fetch that PR or MR from origin and branch the worktree from it. Branching from a GitLab merge request requires Claude Code v2.1.233 or later
Anthropic's own wording. Read off CLI reference, captured 2026-09-26.
In the changelogs
22Releases whose published page names --worktree.
-
v2.1.302
The suggested resume command can include an environment variable
The command Claude Code suggests for resuming a session can now start with an environment variable setting, such as
X=1 claude --resume <id>found in this entry's text, named in this entry
-
v2.1.300
Plugin WorktreeCreate hooks now run when you start with --worktree
Claude Code now loads plugins' WorktreeCreate hooks before creating a --worktree, so a plugin can handle worktree creation
found in this entry's text, named in this entry
-
v2.1.300
Plugin
WorktreeCreatehooks now run when starting with--worktreeStarting with
--worktreenow sets up plugin worktree hooks first, so a plugin'sWorktreeCreatehook can runfound in this entry's text, named in this entry
-
v2.1.300
--worktreefrom a pull request now tracks its host and names the head commitWith
--worktreeand a pull request, Claude Code now passes on which host the request came from and shows the head commit in its messagefound in this entry's text, named in this entry
-
v2.1.300
Worktrees made from a PR number now check they got the right PR
When
--worktreeuses a pull or merge request number, Claude Code fetches the full PR reference and refuses if it can't tell which commit is meantfound in this entry's text, named in this entry
-
v2.1.299
The resume command shown on exit now works for worktree sessions
When you exit a session that ran in a worktree, Claude Code now prints a resume command that includes
--worktreefound in this entry's text, named in this entry
-
v2.1.299
Worktrees from a bare repository layout now fail early with a clear message
Creating a worktree from a folder whose .git points to a bare repository now stops at once and tells you where to start Claude Code instead
found in this entry's text, named in this entry
-
v2.1.290
Worktree error messages reworded and no longer show other paths
Errors when creating a worktree no longer name other folders or give ready-made delete commands, and suggest another
--worktreenamefound in this entry's text, named in this entry
-
v2.1.290
Clearer message when a worktree name is already taken
If a worktree name collides, Claude Code now says the existing registration was left in place and suggests a different
--worktreenamefound in this entry's text, named in this entry
-
v2.1.285
New --desktop flag, and background commands now accept options in front of them
--desktopopens the Claude Desktop app and now errors when combined with background or worktree optionsfound in this entry's text
-
v2.1.281
--tmux worktree relaunch absolutizes path arguments
When --tmux relaunches Claude Code for a worktree, relative file paths in flags are now turned into full paths
found in this entry's text, named in this entry
-
v2.1.281
tmux worktree fast path now enforces managed policy
Starting Claude Code with
--tmuxand--worktreenow applies your organisation's managed policy and exits if the policy refusesfound in this entry's text, named in this entry
-
v2.1.281
claude --tmux --worktreepasses a sanitized env to tmux, stops parsing at--, and forwards args differentlyclaude --tmux --worktree now gives tmux an explicit environment, stops reading its flags at --, and forwards arguments differently
found in this entry's text, named in this entry
-
v2.1.239
Command-line flag parsing rewritten around an explicit table of value-taking flags
Flags that take values no longer swallow or drop their arguments, and
--is handled.found in this entry's text
-
v2.1.239
worktree.locationsetting for Desktop SSH sessionsA
worktree.locationsetting tells the desktop app where to create worktrees for SSH sessions; the CLI ignores it.found in this entry's text
- v2.1.136
-
v2.1.136
Clearer Worktree Setup Failures
found in this entry's text
-
v2.1.133
Worktree Base Ref Setting
found in this entry's text
-
v2.1.101
Worktree-Aware Session Resume
found in this entry's text
-
v2.1.85
Worktree Support for Non-Git VCS
found in this entry's text
-
v2.1.48
Git Worktree Mode
found in this entry's text
-
v2.1.38
Worktree Symlink Configuration
found in this entry's text
First cited
6The earliest release whose published evidence quoted --worktree was v2.1.48, 19 Feb 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.
Presence across releases
1Build by build
149One row per release since the first build this name was read out of. Absent means the build was read and the name was not in it, never mined means no bundle for that release was ever archived, and a declared type or a default is only ever what that release's own bundle stated.
Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the CLI flag does. All CLI flags.