Why does a fresh `claude --worktree` session lack your .env file, your node_modules and your unpushed commits, and what fixes each?
answer
- a fresh checkout has tracked files only
- a gitignore-syntax file at the root
- link big directories instead of copying
- fresh against head as the base
- a creation hook skips the include file
basics
~20 sA Claude Code worktree is a fresh checkout of tracked files from the remote default branch. List gitignored files in .worktreeinclude, symlink or reinstall dependencies with worktree.symlinkDirectories, and set worktree.baseRef to head to keep unpushed commits.
solid answer
~40 sClaude Code creates the worktree with git, which checks out only tracked files, and by default branches it from the repository's default branch on the remote (`worktree.baseRef: "fresh"`). So `.env` is missing because it is gitignored, `node_modules` is missing because it was never committed, and your unpushed commits are missing because the base is `origin`'s default branch. Fix them separately: a `.worktreeinclude` file at the project root, in `.gitignore` syntax, copies files that match a pattern and are also gitignored; `worktree.symlinkDirectories` links large directories such as `node_modules` instead of duplicating them, or you install dependencies in the worktree; and `worktree.baseRef: "head"` branches from your local `HEAD`. Uncommitted edits never come along. If a `WorktreeCreate` hook replaces the git logic, `.worktreeinclude` is not processed and the hook must copy those files itself.
code
json · 6 lines{
"worktree": {
"baseRef": "head",
"symlinkDirectories": ["node_modules", ".cache"]
}
}go deeper
Remember that a worktree holds only tracked files, so .env and installed dependencies are missing until you add them.
Explain .worktreeinclude, the fresh and head values of worktree.baseRef, and when to symlink dependencies rather than reinstall them.
Diagnose a broken worktree by layer: base commit, ignored files, dependencies, LFS pointers, and whether a WorktreeCreate hook bypassed the git path that reads .worktreeinclude.
Weigh shared symlinked dependencies against per-worktree installs: speed and disk against one session's install silently changing every other session's environment.
## Why a worktree starts empty-handed When Claude Code starts a session with `--worktree`, isolates a subagent with `isolation: worktree`, or moves a background session into its own checkout, it creates a **git worktree**: a separate working directory with its own branch. Git populates it from a commit, so it contains **tracked files only**. Three things developers expect are absent: - **Gitignored configuration** such as `.env` or `.env.local`, because git never tracked it. - **Installed dependencies** such as `node_modules` or a virtualenv, for the same reason. - **Unpushed local work**, because the default base is not your current `HEAD`. Each has its own fix, and mixing them up is the usual mistake. ## Choosing the base commit: `worktree.baseRef` The `worktree` settings object controls creation. `worktree.baseRef` accepts exactly two values: | Value | Branches from | Use it when | |---|---|---| | `"fresh"` (default) | the repository's default branch on `origin`, fetched if it has not been fetched in the last 24 hours | the task should start from a clean tree matching the remote | | `"head"` | your current local `HEAD`, including unpushed commits | the task builds on in-progress feature-branch work | Two details matter. First, `baseRef` cannot be a branch name; to start from a specific existing branch, create the worktree yourself with git and start `claude` inside it. Second, `"head"` means a commit, so **uncommitted edits** in your main checkout still do not come along; commit them first. If the fetch fails, the locally cached `origin/HEAD` is used; with no remote, or no cached `origin/HEAD` that can be fetched, a fresh worktree falls back to your local `HEAD`. ## Carrying gitignored files: `.worktreeinclude` Add a `.worktreeinclude` file to the project root. It uses `.gitignore` syntax, and Claude Code copies a file into each new worktree only when it **matches a pattern and is also gitignored**, so tracked files are never duplicated: ``` .env .env.local config/secrets.json ``` The file applies to every worktree Claude Code creates with git: `--worktree` sessions, subagent worktrees and desktop parallel sessions. It is a file, not a settings key; the settings reference itself points you to it for `.env`. ## Dependencies and large monorepos - **Reinstall**: ask Claude to install dependencies in the worktree, or run your setup there yourself. Slow, but each worktree gets its own tree. - **Symlink**: `worktree.symlinkDirectories`, an array of paths relative to the repository root, links directories such as `node_modules` or `.cache` from the main repository into every new worktree instead of duplicating them on disk. The trade-off is that the linked directory is shared, so one session's install changes it for all. - **Sparse checkout**: `worktree.sparsePaths` checks out only the listed directories plus root-level files, which makes creation faster in a large monorepo. - **Git LFS**: if LFS was set up with `git lfs install --local`, the worktree holds pointer files because Claude Code skips the repository's own filter drivers; run `git lfs pull` inside it. ## When a hook creates the worktree A `WorktreeCreate` hook **replaces** the default `git worktree` logic entirely, which is how teams on another version control system get isolation. Because the git path no longer runs, `.worktreeinclude` is **not processed**: the hook script has to copy `.env` and friends itself. The hook prints the created directory's path on stdout, and any non-zero exit aborts creation. ## Telling the gaps apart The symptom usually names the layer: - **Tests fail on missing configuration or credentials**: a gitignored file did not come across; check `.worktreeinclude`, or the hook if one creates worktrees. - **Missing modules or tools on the first build**: dependencies were never installed in the worktree; install them or link them. - **The code looks old, or your feature is absent**: the base is `"fresh"`, and your work lives in unpushed commits or on a branch the worktree did not start from. - **Large binary files are a few lines of text**: Git LFS pointers; pull the real content. Keep the `worktree` settings in the project's `.claude/settings.json` so everyone's worktrees behave the same. `.worktreeinclude` lists patterns, not contents, so committing it exposes no secret. ## A setup checklist 1. Commit or push what the parallel task needs to see, or set `worktree.baseRef` to `"head"`. 2. Add `.worktreeinclude` for gitignored configuration. 3. Decide between reinstalling dependencies and `worktree.symlinkDirectories`. 4. In a monorepo, consider `worktree.sparsePaths`. 5. If a `WorktreeCreate` hook is configured, move the file copying into the hook. Get these right once in project settings and every worktree session, subagent and background session starts ready to build and test.
- You need a worktree session on an existing branch called `release-2`. Can `worktree.baseRef` do that?No. `worktree.baseRef` accepts only `"fresh"` and `"head"`, never a branch name. Create the worktree yourself with git on that branch, `cd` into it and start `claude` there. The session gets the same isolation and shared state; only the creation step is yours.
- A `WorktreeCreate` hook copies nothing and the session has no `.env`. Why didn't `.worktreeinclude` help?Because the hook replaced git's creation logic, and `.worktreeinclude` is processed only on that git path. With a `WorktreeCreate` hook configured, the hook script must copy gitignored configuration into the directory it creates before printing that directory's path.
- .worktreeinclude copies every listed file into the worktree, tracked or not.
- worktree.baseRef can name a branch to start the worktree from.
- With baseRef set to head, uncommitted edits in the main checkout appear in the worktree.
- .worktreeinclude still applies when a WorktreeCreate hook creates the worktree.
- worktree.symlinkDirectories gives each worktree its own private copy of node_modules.