{"name":"--worktree","slug":"worktree","family":"cli","title":"CLI flags","noun":"CLI flag","description":"Start Claude in an isolated [git worktree](\/docs\/en\/worktrees) 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](\/docs\/en\/worktrees#branch-from-a-pull-request). Branching from a GitLab merge request requires Claude Code v2.1.233 or later","description_source":"docs","described_by":{"doc":"claude-code\/cli-reference","title":"CLI reference"},"presence":{"first_seen":"2.1.138","removed_in":null,"in_current_build":true,"newest_mined":"2.1.308","builds":149,"mined_builds":149,"first_cited":{"version":"2.1.48","released_at":"2026-02-19 20:50:30","spans":6}},"aliases":["-w"],"entries":[{"version":"2.1.302","anchor":"resume-advice-command-can-carry-an-env-assignment-prefix","heading":"The suggested resume command can include an environment variable","line":"The command Claude Code suggests for resuming a session can now start with an environment variable setting, such as `X=1 claude --resume <id>`","released_at":"2026-10-16 16:48:28","reason":"found in this entry's text, named in this entry"},{"version":"2.1.300","anchor":"worktree-creation-plugin-worktreecreate-hooks-registered-fi","heading":"Plugin WorktreeCreate hooks now run when you start with --worktree","line":"Claude Code now loads plugins' WorktreeCreate hooks before creating a --worktree, so a plugin can handle worktree creation","released_at":"2026-10-14 14:27:26","reason":"found in this entry's text, named in this entry"},{"version":"2.1.300","anchor":"plugin-worktreecreate-hooks-are-now-registered-before-work","heading":"Plugin WorktreeCreate hooks now run when starting with --worktree","line":"Starting with `--worktree` now sets up plugin worktree hooks first, so a plugin's `WorktreeCreate` hook can run","released_at":"2026-10-14 14:27:26","reason":"found in this entry's text, named in this entry"},{"version":"2.1.300","anchor":"worktree-pr-creation-supports-a-forge-and-uses-head-commit","heading":"--worktree from a pull request now tracks its host and names the head commit","line":"With `--worktree` and a pull request, Claude Code now passes on which host the request came from and shows the head commit in its message","released_at":"2026-10-14 14:27:26","reason":"found in this entry's text, named in this entry"},{"version":"2.1.300","anchor":"pr-worktree-fetch-verifies-the-fetched-ref-tengu-melodic-oc","heading":"Worktrees made from a PR number now check they got the right PR","line":"When `--worktree` uses a pull or merge request number, Claude Code fetches the full PR reference and refuses if it can't tell which commit is meant","released_at":"2026-10-14 14:27:26","reason":"found in this entry's text, named in this entry"},{"version":"2.1.299","anchor":"resume-hint-now-includes-worktree-flags-and-advice","heading":"The resume command shown on exit now works for worktree sessions","line":"When you exit a session that ran in a worktree, Claude Code now prints a resume command that includes `--worktree`","released_at":"2026-10-14 00:23:19","reason":"found in this entry's text, named in this entry"},{"version":"2.1.299","anchor":"worktree-creation-refuses-bare-repository-layouts-with-a-cle","heading":"Worktrees from a bare repository layout now fail early with a clear message","line":"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","released_at":"2026-10-14 00:23:19","reason":"found in this entry's text, named in this entry"},{"version":"2.1.290","anchor":"worktree-creation-errors-reworded-and-sanitized","heading":"Worktree error messages reworded and no longer show other paths","line":"Errors when creating a worktree no longer name other folders or give ready-made delete commands, and suggest another `--worktree` name","released_at":"2026-10-05 18:12:44","reason":"found in this entry's text, named in this entry"},{"version":"2.1.290","anchor":"worktree-registration-error-hint-names-worktree","heading":"Clearer message when a worktree name is already taken","line":"If a worktree name collides, Claude Code now says the existing registration was left in place and suggests a different `--worktree` name","released_at":"2026-10-05 18:12:44","reason":"found in this entry's text, named in this entry"},{"version":"2.1.285","anchor":"desktop-flag-rejected-when-combined-with-background-or-wor","heading":"New --desktop flag, and background commands now accept options in front of them","line":"`--desktop` opens the Claude Desktop app and now errors when combined with background or worktree options","released_at":"2026-09-29 17:32:09","reason":"found in this entry's text"}],"entries_total":22,"docs":[{"source":"claude-code","path":"cli-reference","title":"CLI reference","documented":true},{"source":"claude-code","path":"changelog","title":"Claude Code changelog","documented":false},{"source":"claude-code","path":"claude-directory","title":"Explore the .claude directory","documented":false},{"source":"claude-code","path":"common-workflows","title":"Common workflows","documented":false},{"source":"claude-code","path":"corporate-launcher","title":"Run Claude Code behind a corporate launcher","documented":false},{"source":"claude-code","path":"desktop","title":"Desktop application","documented":false},{"source":"claude-code","path":"hooks","title":"Hooks reference","documented":false},{"source":"claude-code","path":"hooks-guide","title":"Automate actions with hooks","documented":false},{"source":"claude-code","path":"large-codebases","title":"Set up Claude Code in a monorepo or large codebase","documented":false},{"source":"claude-code","path":"settings","title":"Claude Code settings","documented":false}],"docs_total":13,"gates":[],"related":[],"url":"https:\/\/changelogs.core-directive.com\/reference\/cli\/worktree","family_url":"https:\/\/changelogs.core-directive.com\/reference\/cli.json"}