[{"data":1,"prerenderedAt":55},["ShallowReactive",2],{"blog-claude-code-git-worktrees":3,"blog-related-claude-code-git-worktrees":39},{"slug":4,"title":5,"description":6,"category":7,"categoryId":8,"keyword":9,"date":10,"minutes":11,"body":12,"html":13,"headings":14},"claude-code-git-worktrees","Git worktrees with Claude Code: parallel features, no conflicts","Run Claude Code in a git worktree with one flag: separate branches, no stepping on each other's files. Setup, cleanup, base branches and the gotchas.","Workflows","workflows","claude code git worktrees","2026-11-17",5,"A git worktree is a second checkout of the same repository, in its own folder and on its own branch. Start Claude Code in one with `claude --worktree \u003Cname>` and it can build a feature while another session fixes a bug somewhere else, without either one touching the other's files. This page covers the commands, what happens when you exit, and the things that surprise people the first time.\n\n## Why do parallel Claude Code sessions collide in one checkout?\n\nTwo sessions in the same folder share one working tree. If both edit `src\u002Fapi.ts`, the second write lands on top of the first, and a `git commit` in one session picks up the half-finished work of the other. Claude Code tracks only its own edits, so neither session knows what the other did.\n\nA worktree fixes that at the file level: each session has its own copy of the files and its own branch, while the repository history and the remote stay shared. It is the same idea as cloning the repo twice, without the second `.git` folder and the second fetch.\n\n## How do you start Claude Code in a worktree?\n\n```sh\nclaude --worktree feature-auth\n```\n\n`-w` is the short form. Claude Code creates the worktree under `.claude\u002Fworktrees\u002Ffeature-auth\u002F` at the repository root, on a new branch named `worktree-feature-auth`, and starts the session inside it. Run the same command with another name in a second terminal and you have two isolated sessions. Leave the name out and Claude generates one.\n\nA few rules from the docs:\n\n- The repository needs at least one commit.\n- Interactive runs need the folder to be trusted, so run plain `claude` there once first.\n- Add `.claude\u002Fworktrees\u002F` to your `.gitignore`, or the worktrees show up as untracked files in your main checkout.\n\nYou can also ask for it mid-session (\"work in a worktree\"); Claude uses its `EnterWorktree` tool and moves there.\n\n### How do you set up the environment inside a worktree?\n\nA worktree is a fresh checkout, so anything gitignored is missing: `node_modules`, `.env`, build output. Two ways to deal with it.\n\nAsk Claude to install dependencies on the first prompt, or add a `.worktreeinclude` file at the project root. It uses `.gitignore` syntax, and files that match a pattern and are also gitignored get copied into every new worktree:\n\n```text\n.env\n.env.local\nconfig\u002Fsecrets.json\n```\n\nFor big folders you do not want duplicated, the settings reference lists `worktree.symlinkDirectories` (symlink instead of copy) and `worktree.sparsePaths` (check out only the directories you need). Check that page for the exact shape before using them.\n\n## Which branch does a worktree start from?\n\nBy default a new worktree branches from the repository's default branch on the remote, usually `main`, so it starts clean and does not carry your unpushed commits. If you want it to start from your current work, set `worktree.baseRef` in settings:\n\n```json\n{\n  \"worktree\": {\n    \"baseRef\": \"head\"\n  }\n}\n```\n\n`\"fresh\"` is the default and `\"head\"` branches from your local `HEAD`. The setting cannot name a branch. To start from a specific existing branch, create the worktree yourself (below).\n\nTo review a pull request in isolation, pass its number with a `#`, quoted so the shell does not read it as a comment:\n\n```sh\nclaude --worktree \"#1234\"\n```\n\nClaude Code fetches the PR's head from `origin` and checks it out at `.claude\u002Fworktrees\u002Fpr-1234`. A pull request URL works too.\n\n## What happens to the worktree when you exit?\n\nClaude checks whether removing it would lose work.\n\n| State when you exit | What happens |\n| --- | --- |\n| Clean, session unnamed | Worktree and branch are removed automatically |\n| Clean, session named | Claude asks first, so you can keep it |\n| Changed files or new commits | Claude asks whether to keep or remove it |\n\nKeeping preserves the folder and the branch. Claude prints the command to come back, in the form `claude --worktree \u003Cname> --resume`. Removing deletes the directory and its branch together with whatever was in them, so read the prompt. Runs with `-p` have no exit prompt and are never cleaned up automatically; remove those with `git worktree remove`.\n\nThe branch is a normal branch. Merge it, or push it and open a pull request, as in [commit, push and open a PR with Claude Code](\u002Fblog\u002Fclaude-code-commit-and-pull-requests).\n\n## Can subagents and background sessions use worktrees?\n\nYes, and this is where worktrees pay off most. Add `isolation: worktree` to a [custom subagent](\u002Fblog\u002Fclaude-code-subagents)'s frontmatter and every run gets a temporary worktree, removed when the subagent finishes without changes:\n\n```md\n---\nname: refactorer\ndescription: Applies mechanical refactors across many files\nisolation: worktree\n---\n\nApply the requested refactor across every affected file, then run the tests\nand report the results.\n```\n\nBackground sessions started with `claude --bg` move into a worktree under `.claude\u002Fworktrees\u002F` before they edit anything, unless they are already in one or the folder is not a git repository. More on keeping track of those in [running several Claude Code sessions at once](\u002Fblog\u002Frun-multiple-claude-code-sessions).\n\n## How do you manage worktrees by hand?\n\nWhen you need a specific base branch or a worktree outside the repo, use git directly and start Claude inside it:\n\n```sh\ngit worktree add ..\u002Fshop-feature-a -b feature-a\ncd ..\u002Fshop-feature-a\nclaude\n```\n\n`git worktree list` shows them all, and `git worktree remove ..\u002Fshop-feature-a` deletes one. Claude Code treats a worktree made this way like any other checkout; the shared-state notes below apply to both kinds.\n\n## What do worktrees still share with the main checkout?\n\nIsolation is about files, not everything:\n\n- **The `.git` directory.** Commits, branches and stashes live in one repository. A branch checked out in one worktree cannot be checked out in another.\n- **Permission approvals.** Choosing \"Yes, and don't ask again\" in a worktree session saves the rule to the main checkout's `.claude\u002Fsettings.local.json`, so it applies everywhere in that repo and outlives the worktree.\n- **Ports and databases.** Two worktrees both running `pnpm dev` fight over port 3000, and both talk to the same local database. Give each its own port.\n- **Untracked skills, agents and commands.** If a worktree has no `.claude\u002Fskills` of its own, Claude Code reads the main checkout's.\n\nDependencies are the other cost: a worktree with its own `node_modules` is slow to create on a large project, which is where symlinking helps.\n\n## In Relais\n\nRelais has this built in as a checkbox. Under the new-session composer, \"Own worktree and branch\" gives the session a checkout of its own, on a branch named `relais\u002F\u003Cid>` made from the repository's current branch; a Board task has a worktree chip for the same thing. The Changes tab shows the worktree, and the branch chip in the session header merges it back into the branch it came from, or deletes it, then archives the session. Without the checkbox, sessions share the branch each repository is on and Commit takes only the files the session changed. See [features](\u002Ffeatures) and the [FAQ](\u002Ffaq).","\u003Cp>A git worktree is a second checkout of the same repository, in its own folder and on its own branch. Start Claude Code in one with \u003Ccode>claude --worktree &lt;name&gt;\u003C\u002Fcode> and it can build a feature while another session fixes a bug somewhere else, without either one touching the other&#39;s files. This page covers the commands, what happens when you exit, and the things that surprise people the first time.\u003C\u002Fp>\n\u003Ch2 id=\"why-do-parallel-claude-code-sessions-collide-in-one-checkout\">\u003Ca class=\"anchor\" href=\"#why-do-parallel-claude-code-sessions-collide-in-one-checkout\" aria-label=\"Link to this section\">#\u003C\u002Fa>Why do parallel Claude Code sessions collide in one checkout?\u003C\u002Fh2>\n\u003Cp>Two sessions in the same folder share one working tree. If both edit \u003Ccode>src\u002Fapi.ts\u003C\u002Fcode>, the second write lands on top of the first, and a \u003Ccode>git commit\u003C\u002Fcode> in one session picks up the half-finished work of the other. Claude Code tracks only its own edits, so neither session knows what the other did.\u003C\u002Fp>\n\u003Cp>A worktree fixes that at the file level: each session has its own copy of the files and its own branch, while the repository history and the remote stay shared. It is the same idea as cloning the repo twice, without the second \u003Ccode>.git\u003C\u002Fcode> folder and the second fetch.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-start-claude-code-in-a-worktree\">\u003Ca class=\"anchor\" href=\"#how-do-you-start-claude-code-in-a-worktree\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you start Claude Code in a worktree?\u003C\u002Fh2>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude --worktree feature-auth\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>-w\u003C\u002Fcode> is the short form. Claude Code creates the worktree under \u003Ccode>.claude\u002Fworktrees\u002Ffeature-auth\u002F\u003C\u002Fcode> at the repository root, on a new branch named \u003Ccode>worktree-feature-auth\u003C\u002Fcode>, and starts the session inside it. Run the same command with another name in a second terminal and you have two isolated sessions. Leave the name out and Claude generates one.\u003C\u002Fp>\n\u003Cp>A few rules from the docs:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>The repository needs at least one commit.\u003C\u002Fli>\n\u003Cli>Interactive runs need the folder to be trusted, so run plain \u003Ccode>claude\u003C\u002Fcode> there once first.\u003C\u002Fli>\n\u003Cli>Add \u003Ccode>.claude\u002Fworktrees\u002F\u003C\u002Fcode> to your \u003Ccode>.gitignore\u003C\u002Fcode>, or the worktrees show up as untracked files in your main checkout.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>You can also ask for it mid-session (&quot;work in a worktree&quot;); Claude uses its \u003Ccode>EnterWorktree\u003C\u002Fcode> tool and moves there.\u003C\u002Fp>\n\u003Ch3 id=\"how-do-you-set-up-the-environment-inside-a-worktree\">\u003Ca class=\"anchor\" href=\"#how-do-you-set-up-the-environment-inside-a-worktree\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you set up the environment inside a worktree?\u003C\u002Fh3>\n\u003Cp>A worktree is a fresh checkout, so anything gitignored is missing: \u003Ccode>node_modules\u003C\u002Fcode>, \u003Ccode>.env\u003C\u002Fcode>, build output. Two ways to deal with it.\u003C\u002Fp>\n\u003Cp>Ask Claude to install dependencies on the first prompt, or add a \u003Ccode>.worktreeinclude\u003C\u002Fcode> file at the project root. It uses \u003Ccode>.gitignore\u003C\u002Fcode> syntax, and files that match a pattern and are also gitignored get copied into every new worktree:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Ccode>.env\n.env.local\nconfig\u002Fsecrets.json\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>For big folders you do not want duplicated, the settings reference lists \u003Ccode>worktree.symlinkDirectories\u003C\u002Fcode> (symlink instead of copy) and \u003Ccode>worktree.sparsePaths\u003C\u002Fcode> (check out only the directories you need). Check that page for the exact shape before using them.\u003C\u002Fp>\n\u003Ch2 id=\"which-branch-does-a-worktree-start-from\">\u003Ca class=\"anchor\" href=\"#which-branch-does-a-worktree-start-from\" aria-label=\"Link to this section\">#\u003C\u002Fa>Which branch does a worktree start from?\u003C\u002Fh2>\n\u003Cp>By default a new worktree branches from the repository&#39;s default branch on the remote, usually \u003Ccode>main\u003C\u002Fcode>, so it starts clean and does not carry your unpushed commits. If you want it to start from your current work, set \u003Ccode>worktree.baseRef\u003C\u002Fcode> in settings:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"json\">\u003Ccode>{\n  \u003Cspan class=\"hljs-string\">\"worktree\"\u003C\u002Fspan>: {\n    \u003Cspan class=\"hljs-string\">\"baseRef\"\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">\"head\"\u003C\u002Fspan>\n  }\n}\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>&quot;fresh&quot;\u003C\u002Fcode> is the default and \u003Ccode>&quot;head&quot;\u003C\u002Fcode> branches from your local \u003Ccode>HEAD\u003C\u002Fcode>. The setting cannot name a branch. To start from a specific existing branch, create the worktree yourself (below).\u003C\u002Fp>\n\u003Cp>To review a pull request in isolation, pass its number with a \u003Ccode>#\u003C\u002Fcode>, quoted so the shell does not read it as a comment:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude --worktree &quot;#1234&quot;\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Claude Code fetches the PR&#39;s head from \u003Ccode>origin\u003C\u002Fcode> and checks it out at \u003Ccode>.claude\u002Fworktrees\u002Fpr-1234\u003C\u002Fcode>. A pull request URL works too.\u003C\u002Fp>\n\u003Ch2 id=\"what-happens-to-the-worktree-when-you-exit\">\u003Ca class=\"anchor\" href=\"#what-happens-to-the-worktree-when-you-exit\" aria-label=\"Link to this section\">#\u003C\u002Fa>What happens to the worktree when you exit?\u003C\u002Fh2>\n\u003Cp>Claude checks whether removing it would lose work.\u003C\u002Fp>\n\u003Cdiv class=\"table-wrap\">\u003Ctable>\u003Cthead>\u003Ctr>\u003Cth>State when you exit\u003C\u002Fth>\u003Cth>What happens\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd>Clean, session unnamed\u003C\u002Ftd>\u003Ctd>Worktree and branch are removed automatically\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>Clean, session named\u003C\u002Ftd>\u003Ctd>Claude asks first, so you can keep it\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>Changed files or new commits\u003C\u002Ftd>\u003Ctd>Claude asks whether to keep or remove it\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>Keeping preserves the folder and the branch. Claude prints the command to come back, in the form \u003Ccode>claude --worktree &lt;name&gt; --resume\u003C\u002Fcode>. Removing deletes the directory and its branch together with whatever was in them, so read the prompt. Runs with \u003Ccode>-p\u003C\u002Fcode> have no exit prompt and are never cleaned up automatically; remove those with \u003Ccode>git worktree remove\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cp>The branch is a normal branch. Merge it, or push it and open a pull request, as in \u003Ca href=\"\u002Fblog\u002Fclaude-code-commit-and-pull-requests\">commit, push and open a PR with Claude Code\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"can-subagents-and-background-sessions-use-worktrees\">\u003Ca class=\"anchor\" href=\"#can-subagents-and-background-sessions-use-worktrees\" aria-label=\"Link to this section\">#\u003C\u002Fa>Can subagents and background sessions use worktrees?\u003C\u002Fh2>\n\u003Cp>Yes, and this is where worktrees pay off most. Add \u003Ccode>isolation: worktree\u003C\u002Fcode> to a \u003Ca href=\"\u002Fblog\u002Fclaude-code-subagents\">custom subagent\u003C\u002Fa>&#39;s frontmatter and every run gets a temporary worktree, removed when the subagent finishes without changes:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"md\">\u003Ccode>---\nname: refactorer\ndescription: Applies mechanical refactors across many files\nisolation: worktree\n---\n\nApply the requested refactor across every affected file, then run the tests\nand report the results.\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Background sessions started with \u003Ccode>claude --bg\u003C\u002Fcode> move into a worktree under \u003Ccode>.claude\u002Fworktrees\u002F\u003C\u002Fcode> before they edit anything, unless they are already in one or the folder is not a git repository. More on keeping track of those in \u003Ca href=\"\u002Fblog\u002Frun-multiple-claude-code-sessions\">running several Claude Code sessions at once\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-manage-worktrees-by-hand\">\u003Ca class=\"anchor\" href=\"#how-do-you-manage-worktrees-by-hand\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you manage worktrees by hand?\u003C\u002Fh2>\n\u003Cp>When you need a specific base branch or a worktree outside the repo, use git directly and start Claude inside it:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>git worktree add ..\u002Fshop-feature-a -b feature-a\ncd ..\u002Fshop-feature-a\nclaude\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>git worktree list\u003C\u002Fcode> shows them all, and \u003Ccode>git worktree remove ..\u002Fshop-feature-a\u003C\u002Fcode> deletes one. Claude Code treats a worktree made this way like any other checkout; the shared-state notes below apply to both kinds.\u003C\u002Fp>\n\u003Ch2 id=\"what-do-worktrees-still-share-with-the-main-checkout\">\u003Ca class=\"anchor\" href=\"#what-do-worktrees-still-share-with-the-main-checkout\" aria-label=\"Link to this section\">#\u003C\u002Fa>What do worktrees still share with the main checkout?\u003C\u002Fh2>\n\u003Cp>Isolation is about files, not everything:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>The \u003Ccode>.git\u003C\u002Fcode> directory.\u003C\u002Fstrong> Commits, branches and stashes live in one repository. A branch checked out in one worktree cannot be checked out in another.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Permission approvals.\u003C\u002Fstrong> Choosing &quot;Yes, and don&#39;t ask again&quot; in a worktree session saves the rule to the main checkout&#39;s \u003Ccode>.claude\u002Fsettings.local.json\u003C\u002Fcode>, so it applies everywhere in that repo and outlives the worktree.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Ports and databases.\u003C\u002Fstrong> Two worktrees both running \u003Ccode>pnpm dev\u003C\u002Fcode> fight over port 3000, and both talk to the same local database. Give each its own port.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Untracked skills, agents and commands.\u003C\u002Fstrong> If a worktree has no \u003Ccode>.claude\u002Fskills\u003C\u002Fcode> of its own, Claude Code reads the main checkout&#39;s.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Dependencies are the other cost: a worktree with its own \u003Ccode>node_modules\u003C\u002Fcode> is slow to create on a large project, which is where symlinking helps.\u003C\u002Fp>\n\u003Ch2 id=\"in-relais\">\u003Ca class=\"anchor\" href=\"#in-relais\" aria-label=\"Link to this section\">#\u003C\u002Fa>In Relais\u003C\u002Fh2>\n\u003Cp>Relais has this built in as a checkbox. Under the new-session composer, &quot;Own worktree and branch&quot; gives the session a checkout of its own, on a branch named \u003Ccode>relais\u002F&lt;id&gt;\u003C\u002Fcode> made from the repository&#39;s current branch; a Board task has a worktree chip for the same thing. The Changes tab shows the worktree, and the branch chip in the session header merges it back into the branch it came from, or deletes it, then archives the session. Without the checkbox, sessions share the branch each repository is on and Commit takes only the files the session changed. See \u003Ca href=\"\u002Ffeatures\">features\u003C\u002Fa> and the \u003Ca href=\"\u002Ffaq\">FAQ\u003C\u002Fa>.\u003C\u002Fp>\n",[15,18,21,24,27,30,33,36],{"id":16,"text":17},"why-do-parallel-claude-code-sessions-collide-in-one-checkout","Why do parallel Claude Code sessions collide in one checkout?",{"id":19,"text":20},"how-do-you-start-claude-code-in-a-worktree","How do you start Claude Code in a worktree?",{"id":22,"text":23},"which-branch-does-a-worktree-start-from","Which branch does a worktree start from?",{"id":25,"text":26},"what-happens-to-the-worktree-when-you-exit","What happens to the worktree when you exit?",{"id":28,"text":29},"can-subagents-and-background-sessions-use-worktrees","Can subagents and background sessions use worktrees?",{"id":31,"text":32},"how-do-you-manage-worktrees-by-hand","How do you manage worktrees by hand?",{"id":34,"text":35},"what-do-worktrees-still-share-with-the-main-checkout","What do worktrees still share with the main checkout?",{"id":37,"text":38},"in-relais","In Relais",[40,45,50],{"slug":41,"title":42,"description":43,"category":7,"categoryId":8,"keyword":44,"date":10,"minutes":11},"claude-code-multi-repo-projects","Claude Code across several repositories: --add-dir and layouts","How to work with Claude Code on a project split across repos: launch from a parent folder, --add-dir, what config loads from extra folders, and commits.","claude code multiple repositories",{"slug":46,"title":47,"description":48,"category":7,"categoryId":8,"keyword":49,"date":10,"minutes":11},"claude-code-commit-and-pull-requests","Commit, push and open a pull request with Claude Code","How to have Claude Code write commit messages, push a branch and open a PR with gh: prompts that work, permission rules, attribution settings and checks.","claude code commit and pull request",{"slug":51,"title":52,"description":53,"category":7,"categoryId":8,"keyword":54,"date":10,"minutes":11},"undo-claude-code-changes","How to undo what Claude Code changed: \u002Frewind and git","Undo Claude Code's edits with \u002Frewind, git restore and reflog. What checkpoints cover, what they miss (bash, subagents), and habits that make undo painless.","undo claude code changes",1794931098788]